ThinkPHP 6 需通过 composer require topthink/think-api-doc 安装社区扩展，注册服务提供者并在 route/app.php 中绑定 Route::get('api/doc', ' hinkpidocController@index') 路由，配合规范 PHPDoc 注释（如 @param string $name、@return array、RESTful 的 @method）和 @response 示例才能生成 API 文档。
ThinkPHP 6 如何启用内置的 API 文档生成（think-swoole 不行，得用 think-api-doc）
ThinkPHP 官方不自带 API 文档自动生成能力，所谓“内置”其实是社区扩展 think-api-doc，它依赖 think-annotation 解析 PHPDoc 注释。直接装 think-swoole 或改 route.php 不会出文档页面。
- 必须执行
composer require topthink/think-api-doc，注意不是topthink/think-api - 安装后需手动在
app/provider.php中注册服务提供者：thinkpidocServiceProvider::class - 路由必须显式绑定，不能靠自动发现——在
app/route/app.php里加一行：Route::get('api/doc', '\think\apidoc\Controller@index'); - 访问
/api/doc前，确保所有控制器方法都有完整 PHPDoc，且包含@param、@return、@method（对 RESTful 资源路由尤其关键）
PHPDoc 注释怎么写才被 think-api-doc 正确识别
它只认标准 PHPDoc + ThinkPHP 特定扩展标签，@var、@deprecated 这类完全忽略；@param 类型写 int 没问题，但写 integer 就可能解析失败。
-
@param必须带类型和变量名，如@param string $name 用户昵称；只写@param $name会被跳过 -
@return后面不能跟空格再换行，必须在同一行结束，否则返回值类型为空 - RESTful 方法需用
@method GET|POST|PUT|DELETE显式声明，否则默认只当GET处理 - 路径参数（如
/user/:id）要在注释里用@param int $id 路径ID，不能只靠路由定义推断
接口响应结构不统一导致文档字段缺失怎么办
think-api-doc 不分析实际返回数据，只读 @return 和 @response 标签。如果控制器里用 json(['code'=>0, 'data'=>...])，但注释只写 @return array，文档里就只显示 “array”，看不到具体字段。
- 必须补充
@response示例（支持 JSON 字符串或数组格式），例如：@response {"code":0,"data":{"id":1,"name":"test"}} - 若项目已用
thinkResponse统一封装，建议在基类控制器里写好通用@response模板，子类用@see引用，避免重复 - 不要依赖 IDE 自动生成的 PHPDoc——它常漏掉嵌套对象字段，
@response里嵌套对象要展开写全，否则文档不渲染子字段 - 数组内多类型元素（如混合 string/int）写成
string|int[]会被解析错误，应统一为array并在描述中说明
为什么本地能生成文档，部署到 Nginx 后 404 或空白
核心是 URL 重写和静态资源路径问题。think-api-doc 的前端依赖 dist/ 下的 JS/CSS，这些文件由扩展包发布到 public/static/api-doc/，但 Nginx 默认不代理该路径。
立即学习“PHP免费学习笔记（深入）”；
- 确认执行过
php think api:publish，该命令把前端资源复制到public/static/api-doc/ - Nginx 配置里要显式放行该路径，不能只靠
try_files转给 index.php；加一段：location ^~ /static/api-doc/ { alias /path/to/public/static/api-doc/; } - 检查
config/apedoc.php中的base_url是否匹配线上域名，尤其是带子目录部署时（如https://a.com/api/），这里填错会导致 JS 加载 404 - Chrome 控制台报
Failed to load resource: the server responded with a status of 404 ()且路径是/static/api-doc/js/app.js，基本就是上面两点没配对
文档生成本身不耗性能，但每次请求都实时扫描控制器——上线前务必关掉开发模式下的自动扫描，用 php think api:build 预生成 JSON 文件并配置为静态服务。
