swagger-php 是 ThinkPHP5 生成 Swagger 文档最直接可控的方案，需正确安装、规范注释、稳定生成 swagger.json；推荐用 openapi 命令行工具扫描 app/ 目录并输出至 public/swagger.json，注释须含 @OA\Info 且置于控制器类/方法上，配合 swagger-ui 本地路径配置使用。
swagger-php 是 ThinkPHP5 项目中生成 Swagger 文档最直接、最可控的方案，不需要额外插件——所谓“插件”本质是封装了命令调用或注释扫描逻辑的第三方包，反而容易掩盖问题、限制灵活性。你真正需要的是三件事：正确安装 swagger-php、规范写注释、稳定生成 swagger.json。
为什么别急着装“Swagger插件”
很多 TP5 插件（比如 think-swagger 或 tp5-swagger）本质只是对 swagger-php 的简单包装，有的还硬编码扫描路径、强制使用特定版本、甚至把 @SWG 注解写死在模板里。一旦你遇到以下情况，就会卡住：
-
swagger-php升级到 4.x 后注解前缀变成@OA，插件不更新就报错Class 'SWG\Info' not found - 插件默认只扫
app/controller，但你的 API 在app/api/controller，它就漏掉一半接口 - 插件生成的
swagger.json没法指定输出路径，导致你无法把它放到public/下被swagger-ui正确加载
直接用原生 swagger-php 命令行，参数清晰、路径可控、错误明确。
用 openapi 命令生成 swagger.json（推荐方式）
从 swagger-php 3.0 开始，官方 CLI 工具改名为 openapi，它比旧版 swagger 命令更稳定，支持 PHP 7.4+ 和 ThinkPHP5.1 的命名空间结构。
立即学习“PHP免费学习笔记（深入）”；
在项目根目录执行：
php vendor/zircote/swagger-php/bin/openapi app/ --output public/swagger.json --format json
关键点说明：
-
app/是你要扫描的目录，ThinkPHP5 的控制器通常在app/controller或app/api/controller，按需调整 -
--output public/swagger.json必须指向public/下，否则swagger-ui加载不到 -
--format json显式指定格式，避免某些环境默认输出 YAML 导致前端解析失败 - 如果提示
Class 'OpenApi\Annotations\Info' not found，说明你装的是 2.x 版本但用了 3.x 注解语法，统一用composer require zircote/swagger-php:^3.4锁定 3.4+
注释必须写在控制器类/方法上，不能只靠路由定义
ThinkPHP5 的路由规则（如 Route::post('login', 'User/login')）不会被 swagger-php 解析。文档生成完全依赖 PHPDoc 注释，且必须带 @OA\ 前缀（3.x）或 @SWG\（2.x），不能混用。
一个最小可用示例：
namespace app\api\controller;
<p>use think\Controller;</p><p>/**</p><ul><li>@OA\Info(title="用户服务API", version="1.0.0")
*/
class User extends Controller
{
/**<ul><li>@OA\Post(</li><li>path="/api/user/login",</li><li>summary="用户登录",</li><li>@OA\RequestBody(@OA\JsonContent(required={"username","password"})),</li><li>@OA\Response(response="200", description="成功")</li><li>)
*/
public function login()
{
return json(['token' => 'xxx']);
}
}注意：
-
@OA\Info必须出现在某个类或文件顶部，否则生成的 JSON 缺少根信息，swagger-ui会报TypeError: Cannot read property 'info' of null - 每个接口方法必须有
@OA\Get/@OA\Post等操作注解，否则不会出现在文档里 - 不要在
index.php或中间件里写@OA\注解，swagger-php不扫描它们
swagger-ui 静态资源部署和加载地址要配对
把 swagger-ui 放进 public/ 后，它的 index.html 默认加载的是远程 URL，必须手动改成你本地生成的 swagger.json 路径：
编辑 public/swagger-ui/index.html，找到类似这行：
url: "https://petstore.swagger.io/v2/swagger.json",
替换成：
url: "/swagger.json",
确保这个路径能被浏览器直接访问（即 http://your-domain.com/swagger.json 返回 JSON 内容）。如果 TP5 开启了 URL 重写，/swagger.json 可能被路由拦截，这时要在 public/.htaccess（Apache）或 nginx.conf（Nginx）里加白名单规则，例如 Nginx：
location = /swagger.json {
try_files $uri =404;
}没配对的话，页面空白，控制台报 Failed to load API definition，但错误提示非常隐蔽。
最常被忽略的其实是注释位置和 @OA\Info 的存在性——它不报错，但生成的 JSON 是空壳，swagger-ui 打开后连标题都不显示。生成完先用浏览器直接打开 /swagger.json，确认里面有 "info": { "title": ... } 这段，再去看 UI 页面。
