thinkphp 8 swagger 文档生成失败主因是 zircote/swagger-php 未正确扫描注解或 openapi.json 不符合 openapi 3.0 规范；注解须紧贴方法/类、显式声明参数与请求体、path 必须匹配真实路由、输出路径需可公开访问、必须配置 @oa\server 和 header，且生成命令路径不能出错。
ThinkPHP 8 项目里 Swagger 文档生成失败，90% 是因为 zircote/swagger-php 没正确扫描到注解，或生成的 openapi.json 不符合 OpenAPI 3.0 规范——浏览器打开 Swagger UI 就报 Failed to load spec，不是前端问题，是后端没吐出合法 JSON。
注解写在哪、怎么被扫描到
Swagger-PHP 只认 PHPDoc 块里的 @OA\* 注解，且必须紧贴方法或类上方，中间不能空行。它不读路由配置，也不解析控制器继承链，只靠反射扫描实际带注解的可执行方法。
-
@OA\Get、@OA\Post必须写在具体 Action 方法上，不能只写在 Controller 类顶部 - 路径
path="/api/users"必须和你最终暴露给前端的真实 URL 完全一致（含前缀、版本号），比如路由是Route::get('api/v2/users', ...)，注解就得写path="/api/v2/users" - 参数必须显式声明：
@OA\Parameter(name="page", in="query")，函数签名public function index($page = 1)不会自动变成文档参数 - Body 提交必须用
@OA\RequestBody+@OA\JsonContent描述结构，光写@OA\Property不生效
生成命令和输出路径必须精确
运行 vendor/bin/openapi 时，输入路径错一个字母，就可能漏掉全部接口。ThinkPHP 8 默认控制器在 app/controller/，但如果你用了多应用或自定义命名空间，得确认真实路径。
- 命令示例：
php vendor/bin/openapi app/controller/ --output public/swagger.json - 输出路径
public/swagger.json必须能被 Web 服务器直接访问（如http://localhost/swagger.json），Nginx/Apache 不能拦截.json后缀 - 如果生成报错
Class 'OpenApi\Annotations\Get' not found，说明没加use OpenApi\Annotations as OA;或 PHP 版本低于 8.0（旧版需额外装doctrine/annotations） - 大项目建议加内存限制：
php -d memory_limit=-1 vendor/bin/openapi app/controller/ -o public/swagger.json
Swagger UI 能加载但“Try it out”失败
点测试按钮直接 404 或 CORS 报错？大概率是 openapi.json 缺 servers 字段，或者服务器响应头没设对。
- 必须在某处加全局
@OA\Info，里面嵌套@OA\Server，例如：@OA\Server(url="http://localhost:8000/api") - PHP 输出 JSON 前要加
header('Content-Type: application/json; charset=utf-8');，否则某些 Nginx 配置下会触发下载而非渲染 - Swagger UI 的
index.html里默认请求同级openapi.json，路径不匹配就手动改url: "../swagger.json"或用绝对路径 - 开发环境用
php -S时，router.php 要放行 JSON 请求：if (preg_match('/\.json$/', $_SERVER['REQUEST_URI'])) { readfile($_SERVER['DOCUMENT_ROOT'] . $_SERVER['REQUEST_URI']); exit; }
最常被忽略的是：注解里的 path 和框架实际路由不一致、@OA\Info 缺 title 或 version 导致整个 JSON 被 UI 拒绝、以及生成命令扫错了目录——这三处任一出错，文档页面就是空白或报错，没有中间状态。
大量免费API接口：立即使用
涵盖生活服务API、金融科技API、企业工商API、等相关的API接口服务。免费API接口可安全、合规地连接上下游，为数据API应用能力赋能！
