推荐使用官方扩展 topthink/think-swagger，通过解析 Route::rule() 和控制器 @OA 注解自动生成 OpenAPI 3.0 格式的 /api/doc/swagger.json；需显式定义路由、PHP ≥ 7.4、控制器方法含正确 @OA\Get 等标签及参数注解，生产环境须关闭 swagger.enable。
ThinkPHP 6 如何自动扫描路由生成 Swagger JSON
原生 ThinkPHP 不带 Swagger 文档生成功能，必须依赖扩展或手动构造 JSON。推荐使用 topthink/think-swagger（官方维护的轻量扩展），它通过解析 Route::rule() 和控制器注解，自动生成符合 OpenAPI 3.0 规范的 /swagger.json。
安装后需在 app/middleware.php 中注册中间件，并确保所有 API 路由都通过 Route::group() 显式定义——动态闭包路由、未命名路由或未绑定控制器方法的规则会被跳过。
- 控制器方法必须有 PHPDoc 注释，至少包含
@api或@OA\Get等 OpenAPI 标签（用zircote/swagger-php语法） - 不支持
__call动态方法、匿名函数路由、Route::import()加载的外部路由文件 -
swagger.json默认输出路径为/api/doc/swagger.json，可通过配置项swagger.output_path修改
控制器里怎么写注解才能被正确识别
Swagger 扩展只认标准 @OA\ 注解（来自 zircote/swagger-php），不是随便写个 @param 就能生效。最简可用模板如下：
/**
* @OA\Get(
* path="/api/user/{id}",
* summary="获取用户详情",
* @OA\Parameter(
* name="id",
* in="path",
* required=true,
* @OA\Schema(type="integer")
* ),
* @OA\Response(response="200", description="成功")
* )
*/
public function read($id) { ... }
常见失效原因：
立即学习“PHP免费学习笔记（深入）”；
- 漏写
@OA\Get/@OA\Post等顶层操作标签（仅写@param不触发解析） - 参数
in值写成"url"或"query"（正确是"path"/"query"/"header"） - 返回模型用了
@OA\Schema(ref="#/components/schemas/User")，但没在类顶部定义@OA\Schema组件 - PHP 版本低于 7.4 ——
zircote/swagger-phpv4 要求 PHP ≥ 7.4
如何让 Swagger UI 页面和 ThinkPHP 后端同域名访问
扩展默认只提供 /api/doc/swagger.json 接口，不带 UI。要集成 UI，不能直接扔一个 index.html 进 public/ 然后硬编码 URL，否则跨域或 basePath 错位会导致请求 404。
正确做法是：用 ThinkPHP 的 view 渲染 Swagger UI 模板，动态注入 window.onload 中的 url 为相对路径 ./swagger.json；同时确保 Nginx/Apache 开启 Access-Control-Allow-Origin: * 或明确指定前端域名。
- 不要把 Swagger UI 的
dist/整体复制到public/并用静态路径访问——这样无法动态切换环境（如测试服指向/test/swagger.json） - 若启用多模块（如
api模块），需在config/swagger.php中设置'base_path' => '/api'，否则生成的路径会漏前缀 - 生产环境务必关闭
swagger.enable配置，避免暴露内部接口结构
为什么 /swagger.json 返回 500 但日志没报错
典型原因是注解语法错误导致 zircote/swagger-php 解析器静默失败（不抛异常，返回空数组），最终 JSON 编码时遇到 null 报 json_encode() expects parameter 1 to be string, array given 类似错误，但框架已捕获并返回 500，而日志级别不够看不到底层 warning。
- 临时排查：在生成逻辑里加
error_log(print_r($openapi, true), 3, 'php://stderr')，看是否为空 - 检查是否有控制器方法名含非法字符（如中文、短横线），会导致反射失败，整个类被跳过
- 确认
composer dump-autoload -o已执行——新增注解类后未重生成 autoload 可能导致@OA\标签无法识别 - 若用 Swoole 或 RoadRunner，注意注解扫描是一次性缓存的，代码修改后需重启服务进程
注解不是装饰器，没有运行时能力；它纯靠静态分析，任何语法偏差都会导致整块丢失，这点比 Laravel 的 @OA 更脆弱。
