如何通过ThinkPHP结合Swagger快速构建API文档？

本文共计1088个文字，预计阅读时间需要5分钟。

markdownSwagger在ThinkPHP中不是开箱即用的功能，需要依赖注释工具链驱动。直接说结论：

---

装对依赖，别被镜像和权限坑住

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 路径配没配准——四件事里错一个，文档就出不来。