如何通过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。