<p>ThinkPHP 6.0.16需借助swagger-php解析OpenAPI注解生成openapi.json，再由Swagger UI渲染；注解须规范写在控制器方法上方的/* /内，路径需与路由完全一致，推荐命令行生成并静态部署JSON。</p>
ThinkPHP 6.0.16 本身不生成接口文档，必须借助 swagger-php 解析 OpenAPI 注解，并配合 Swagger UI 展示。所谓“自动生成”，本质是静态扫描 PHP 文件中的 @OA\Get、@OA\Post 等注解，输出标准的 openapi.json（或 YAML），再由前端 UI 渲染成可交互页面。
注解写法必须规范
所有 OpenAPI 注解都需写在控制器方法上方的 /** */ 块内，且不能与方法之间有空行；必须用 use OpenApi\Annotations as OA; 导入命名空间。
- 路径
path必须和Route::get('/api/v1/users', ...)中注册的 URL 完全一致（含开头斜杠、不含多余尾部斜杠） - 带参数的路由如
api/v1/users/{id}，注解中要写path="/api/v1/users/{id}"，并额外添加@OA\Parameter - 全局信息（如标题、版本）需在某个控制器类或单独文件顶部用
@OA\Info声明
生成 openapi.json 的可靠方式
推荐使用命令行方式，在项目根目录执行：
./vendor/bin/openapi app/controller -o public/openapi.json
- 若模型（model）或服务（service）里也定义了接口，可追加路径：
app/controller app/model - 确保 PHP 版本 ≥ 7.4（swagger-php 4.x 强制要求）
- 生成后检查
public/openapi.json是否有内容，避免出现No operations defined报错
接入 Swagger UI 展示文档
将 swagger-ui-dist 静态资源放入 public/swagger/ 目录，然后配置一个路由指向它：
立即学习“PHP免费学习笔记（深入）”；
Route::get('swagger', function () {
return readfile(public_path('swagger/index.html'));
});并在 index.html 中把默认请求地址改为你的 JSON 路径，例如：
url: "/openapi.json"
- 确保
openapi.json可通过浏览器直接访问（如http://yourdomain.com/openapi.json） - 不建议用 PHP 动态返回 JSON（如
Route::get('api-docs', [...])），易因缓存或环境差异导致内容陈旧
常见踩坑点
- 误写 ThinkPHP 5.1 风格的
@api、@param注释——TP6 完全不识别，纯属无效注释 - 混用已废弃的
think-apidoc插件，与 TP6 不兼容 -
@OA\Get写在方法内部、或用了单行注释//，工具无法解析 - 路由注册路径和注解
path字符不完全一致（比如大小写、斜杠数量、前缀缺失）
