Swagger UI 在线调试失败的主因是 PHP 未正确生成并暴露符合 OpenAPI 3.0 规范的 openapi.json：字段缺失（如 info.title）、注解位置错误、路径不可访问、MIME 类型未声明、跨域未配置或未重新生成文档。
Swagger UI 能在线调试，但前提是 PHP 必须吐出合法的 openapi.json，且路径可被浏览器直接访问。光放个 index.html 到 public/ 下，90% 的人会卡在空白页或 Failed to load API definition。
php-swagger 生成的 JSON 必须严格符合 OpenAPI 3.0 规范
字段名大小写、嵌套层级、必需字段（如 openapi、info）缺一不可。常见错误包括：
-
@OA\Info漏写title或version，导致整个 JSON 被 UI 拒绝 - 参数
in="path"却没在path字符串里声明对应占位符，例如写了path="/users/{id}"却漏了@OA\Parameter(name="id", in="path") - 响应体用
@OA\JsonContent时，@OA\Items写成@OA\Item（少个 s），JSON 语法合法但 OpenAPI 校验失败 - PHP 输出前没加
header('Content-Type: application/json; charset=utf-8');，某些 Nginx 配置下会触发下载而不是渲染
Swagger UI 静态资源必须能正确请求到 openapi.json
默认情况下，swagger-ui/index.html 会向同级目录请求 openapi.json。你得确保这个路径在 Web 服务器上真实可访问，且不被拦截：
- Apache：检查
.htaccess是否误拒了.json后缀（需显式允许application/jsonMIME 类型） - Nginx：确认没有
location ~ \.json$ { deny all; }这类规则；若用了try_files，要保证/openapi.json不被重写进 PHP 路由 - 路径别名陷阱：比如把 UI 放在
/public/docs/，但生成的 JSON 在/public/openapi.json，就得手动改index.html里的url字段为"../openapi.json"或绝对路径 - 开发时用 PHP 内置服务器（
php -S）要额外路由：在 router.php 中加if (preg_match('/\.(?:png|jpg|jpeg|gif|ico|css|js|json)$/', $_SERVER["REQUEST_URI"])) return false;
注解写在哪、怎么扫描，直接影响生成结果
zircote/swagger-php 只扫描带 @OA\ 注解的 PHP 文件，且依赖 PHP 的反射能力。它不关心你是否“注册了路由”，只认代码里的注释结构：
立即学习“PHP免费学习笔记（深入）”；
- 注解必须写在「可执行方法」上方，不能只写在类或 trait 上（除非是
@OA\Info这类全局注解） - 扫描命令的路径要精确：运行
php vendor/bin/openapi app/Controllers/ --output public/openapi.json，如果控制器实际在app/Http/Controllers/，就会漏掉所有接口 - ThinkPHP/Laravel 等框架中，别把注解写在中间件或服务提供者里——它们不会被当成 API 入口，UI 里也看不到
- 生成时加
-d memory_limit=-1，避免大项目扫描中途 OOM（尤其含大量模型和嵌套 Schema 时）
在线调试失败？先看 Network 和 Console
点击 “Try it out” 没反应，或返回 404/500，不要猜，直接看浏览器开发者工具：
- Network 标签页找那个
openapi.json请求：状态码是不是 404？响应内容是不是 HTML（说明被路由到了首页）？ - 再找实际发出去的 API 请求：URL 是不是拼错了（比如多了一层
/api/v1）？Headers 里有没有漏传Authorization或Content-Type？ - Console 报
CORS error？那不是 Swagger 的问题，是你的 PHP 接口没返回Access-Control-Allow-Origin头——Swagger UI 是纯前端，跨域策略由后端控制 - 点执行后页面卡住？检查响应体是否真为 JSON 格式，有些接口返回 HTML 错误页（如 Laravel 的 404 页面）也会让 UI 解析失败
最常被忽略的是：Swagger UI 本身不处理 PHP 逻辑，它只消费 JSON；而 openapi.json 一旦生成，就和 PHP 代码完全解耦。改了控制器但忘了重新运行 openapi 命令，文档永远是旧的。
