必须写@OA*注解、装zircote/swagger-php、配准路由指向才能生成可用文档；否则空文档或404。注解须置于public方法的PHPDoc块内，路径需与实际路由完全一致，嵌套参数要扁平化拆解，swagger.json路径须在swagger-ui中手动配置为绝对路径。
Swagger 在 ThinkPHP 里不是开箱即用的功能，得靠注释 + 工具链驱动。直接说结论：不写 @OA* 注解、不装 zircote/swagger-php、不配好路由指向，就不可能生成可用的文档。
装对依赖，别被镜像和权限坑住
composer require zircote/swagger-php 是必须的第一步，但实际执行时容易卡在三处：
- 国内网络下没设镜像，会超时或失败 → 运行
composer config repo.packagist composer <a href="https://www.php.cn/link/1569ae888190eb8c53b218b0d529e1e9">https://www.php.cn/link/1569ae888190eb8c53b218b0d529e1e9</a>再重试 - 用宝塔面板 Shell 执行
composer命令报错（如HOME or COMPOSER_HOME must be set）→ 改用服务器终端登录后执行，别信面板 Shell 的环境变量 -
vendor/bin/openapi脚本没执行权限（尤其 Windows WSL 或某些 Docker 环境）→ 手动加权：chmod +x vendor/bin/openapi
装完检查 vendor/zircote/swagger-php 目录是否存在，别只看命令返回 success。
@OA\* 注解必须写在 public 方法上，且路由得真能访问到
ThinkPHP 的think-swagger 或原生 swagger-php 都是静态扫描，它**不运行代码，只读文件**。所以：
- 注释必须写在控制器里明确声明为
public的方法上，private/protected/__invoke/ 中间件里的逻辑，一律不扫描 - 路由必须显式绑定该方法，例如：
Route::post('api/login', 'api.LoginController@login'); - 别用资源路由（
Route::resource）又不加only限定，否则扫描器找不到对应方法入口 - 多级命名空间如
app\api\v2\UserController，得确认扫描路径包含app/api/v2/，否则直接跳过
常见错误现象：swagger.json 里空空如也，或只有 Info 没接口 —— 八成是路由没绑对，或者方法没加 public。
嵌套参数不能写 @param array，得拆成扁平字段
ThinkPHP 生态（尤其是think-swagger）对 PHPDoc 的解析很“直男”：
-
@param array $data→ 完全忽略，不会展开解析内部结构 - 正确写法是手动拆解：
@param string $user_name、@param int $user_age、@param string $user_address_city - 如果参数是 JSON body 里的嵌套对象（如
{"profile": {"nick": "a", "level": 5}}），就得写成：@param string $profile_nick、@param int $profile_level - 必填字段必须加
@required（非标准 PHPDoc，是 think-swagger 特有语法），光靠验证规则'nick|require'不会同步到文档
漏掉这一步，前端看到的字段就是空的，或者类型标成 string 却传了整数，文档和实际行为完全脱节。
立即学习“PHP免费学习笔记（深入）”；
生成 JSON 后，swagger-ui 的 url 要手改，别指望自动识别
vendor/bin/openapi app/ -o public/swagger.json 这条命令能生成文件，但只是第一步。接下来：
- 把
swagger-ui的dist/目录整个丢进public/swagger/ - 编辑
public/swagger/index.html，找到url:那行，改成绝对路径，比如：url: "/swagger.json"（注意开头斜杠） - 如果项目跑在子目录（如
<a href="https://www.php.cn/link/215b64d69046dea9cf81553763cecc92">https://www.php.cn/link/215b64d69046dea9cf81553763cecc92</a>），这里得写成url: "/myapp/swagger.json"，否则 404 - 浏览器访问
/swagger/页面时，F12 看 Network，确认swagger.json返回 200 且内容是合法 JSON —— 有语法错误或路径错，页面只会显示 “Failed to load spec.”
最常被忽略的是：生成的 swagger.json 里可能混入 BOM 或 UTF-8 编码问题，导致解析失败；建议用 VS Code 保存为 “UTF-8 无 BOM” 格式再试。
真正卡住人的从来不是安装命令，而是注解写在哪、路由指没指对、嵌套参数怎么拆、JSON 路径配没配准——四件事里错一个，文档就出不来。
