ThinkPHP 自动生成API文档需工具、注释、路由三者协同；think-swagger要求显式路由与扁平化字段注释，topthink/think-apidoc需专用标签，zircote/swagger-php需OpenAPI规范注解，所有工具均不分析运行时返回值。
ThinkPHP 本身不生成 API 文档，所有“自动生成”都依赖你选对工具、写对注释、配对路由——三者缺一不可。装完扩展就指望 php think api 命令吐出一份完整 Swagger 页面？大概率只看到空列表或报错。
think-swagger 要求显式路由 + 扁平化字段注释
它只扫描 route/app.php 里用 Route::post('api/user', 'api.UserController/save') 这种写法绑定的控制器方法，闭包路由、Route::resource()（没加 only）、中间件内逻辑全被跳过。
-
@param array $data不会被识别，必须拆成@param string $user_name、@param int $user_age等具体字段 - 嵌套参数如
user[profile][avatar]，得写成@param string $user_profile_avatar - 必填字段必须加
@required（think-swagger 特有，非 PHPDoc 标准） - 多级命名空间如
api\v2\UserController，需确认配置中paths包含该目录
topthink/think-apidoc 注释格式完全独立
这是 ThinkPHP6 官方生态方案，不用 OpenAPI 规范，但标签不能混用：必须用 @ApiParams、@ApiReturn，不能夹带 @param 或 @OA\Get。
-
@ApiParams必须写全name、type、required、description，例如@ApiParams(name="id", type="integer", required=true, description="用户ID") - 生成命令是
php think apidoc --module api --path ./public/apidoc --type json，路径和模块名必须与实际目录结构严格一致 - 它不校验注释和验证器是否匹配：validate() 里写了
id|require，但注释漏了required=true，文档里就不会标必填
zircote/swagger-php 支持 OpenAPI 3.0，但注解成本高
如果你项目已对接外部平台，或需要机器可读的 JSON/YAML，这是更通用的选择。但它不认 @param，必须写 @OA\Get、@OA\Parameter 等结构化注解。
立即学习“PHP免费学习笔记（深入）”；
-
path必须和Route::get('api/v1/users', ...)中注册的 URL 完全一致，且开头带/，写成users或/users/（结尾多斜杠）都会导致 Swagger UI 拼接失败 -
@OA\Parameter的in字段只能是query、path、header、cookie，写成url或get会静默忽略 - 响应体必须用
@OA\Response显式声明description，否则部分 UI 渲染器直接空白 - 生成的
openapi.json是静态文件，但 ThinkPHP 默认路由会拦截/api-docs/openapi.json，得加透传路由：Route::get('api-docs/openapi.json', function () { return file_get_contents(public_path() . '/api-docs/openapi.json'); });
别指望 IDE 自动生成的 PHPDoc 能直接用
IDE 补全的 @param $id 没类型、@return 后换行、嵌套对象字段只写顶层、@response 用数组而非 JSON 字符串——这些都会导致字段缺失或解析失败。
-
@param必须带类型和变量名，@param string $name可以，@param $name被跳过 -
@return必须在同一行结束，后面不能空格再换行 -
@response推荐写成 JSON 字符串：@response {"code":0,"data":{"id":1,"name":"test"}}，数组格式可能被某些解析器忽略 - 数组内混合类型（如
string|int[]）会被解析错误，应统一为array并在描述中说明
最容易被忽略的是：所有工具都不分析运行时返回值，只读注释。你控制器里 return json(['code'=>0, 'data'=>['id'=>1]])，但注释只写 @return array，文档里就真只显示 “array” ——字段名、类型、嵌套结构全靠你手动补全。
