Swagger UI 是纯前端应用，需 PHP 项目提供符合 OpenAPI 3.0 规范的 openapi.json 文件并正确托管静态资源，常见问题源于路径错误、JSON 不合法、服务器配置拦截或注解与代码脱节。
Swagger UI 为什么不能直接跑在 PHP 项目里
它本身是个纯前端应用，不依赖后端语言，但需要一个 openapi.json（或 swagger.json）文件作为数据源。PHP 项目要“集成”，本质是两件事：生成这个 JSON 文件 + 把 Swagger UI 的静态资源跑起来。
常见错误现象：Failed to load API definition、CORS error、点开 UI 后空白且控制台报 404 —— 基本都是路径没对上，或者 PHP 没吐出合法 JSON。
- 别把
index.html放到/public下就以为完事了，得确保它能正确请求到/openapi.json（相对路径默认找同级） - PHP 输出的 JSON 必须严格符合 OpenAPI 3.0 规范，字段名大小写、嵌套层级错一个，UI 就不认
- 用 Apache 时注意
.htaccess别拦截了.json请求；Nginx 要确认location ~ \.json$没被 rewrite 掉
用 php-swagger 自动生成 openapi.json
手动写 OpenAPI YAML/JSON 容易漏、难维护，zircote/swagger-php 是目前最稳的 PHP 注解方案。它读代码里的 @OA\ 注解，生成标准 JSON。
使用场景：控制器方法有明确参数、返回结构、状态码，比如 RESTful 接口的 GET /users/{id}。
立即学习“PHP免费学习笔记（深入）”；
- 安装：
composer require zircote/swagger-php - 在控制器方法上方加注解，例如：
@OA\Get(path="/users/{id}", @OA\Parameter(name="id", in="path", required=true, @OA\Schema(type="integer"))) - 生成命令：
php -d memory_limit=-1 vendor/bin/openapi app/Controllers/ --output public/openapi.json（注意输出路径必须能被 Web 服务器直接访问） - 别忘了在 PHP 中设置响应头：
header('Content-Type: application/json; charset=utf-8');，否则某些环境会当文本下载
把 Swagger UI 静态文件接入 PHP 项目
不是“集成 Swagger UI 库”，而是把它当成一组 HTML/CSS/JS 静态资源托管起来。官方 dist 包最干净，别用 CDN（跨域、版本失控、离线失效）。
性能影响：UI 加载慢？大概率是没压缩 JS，或没启用 Gzip。兼容性影响：新版 Swagger UI（v5+）要求浏览器支持 ES2017+，IE 完全不兼容。
- 下载最新 dist：
wget https://github.com/swagger-api/swagger-ui/archive/refs/tags/v5.17.14.tar.gz，解压后取dist/目录 - 把
dist/整体放进public/swagger-ui/，确保public/swagger-ui/index.html可通过/swagger-ui/访问 - 打开
index.html，找到url: "https://petstore.swagger.io/v2/swagger.json"这行，改成：url: "/openapi.json" - 如果 PHP 路由框架（如 Laravel、ThinkPHP）接管了所有请求，得单独放行
/openapi.json和/swagger-ui/.*，否则 404
调试时 curl 命令比 UI 更快定位问题
UI 界面漂亮，但报错模糊。真出问题，先绕过它，直击源头。
容易踩的坑：openapi.json 里写死的 servers 地址和你当前域名不一致，导致 UI 发请求发到别的地方去了；或者 JSON 里混入了 PHP 错误提示（比如 Notice 被 echo 出来），导致 JSON 格式损坏。
- 检查 JSON 是否合法：
curl -s http://localhost/openapi.json | jq .（没 jq 就用在线 JSON 校验器粘贴内容） - 看是否含 PHP 错误：
curl -s -D - http://localhost/openapi.json -o /dev/null，检查响应头有没有X-Powered-By: PHP或Content-Length异常大 - 确认 UI 实际请求地址：
curl -v http://localhost/swagger-ui/ | grep -A5 "url:"，看它最终加载的是哪个 URL - 如果用了 HTTPS 但
openapi.json里servers写的是http://，浏览器会因混合内容阻止请求
复杂点在于：OpenAPI 注解和实际代码逻辑脱节时，文档永远是对的，接口永远是错的——没人会改文档去适配 bug。所以每次改接口，第一件事不是测功能，是重生成并人工核对 openapi.json 里对应段落。
