ThinkPHP环境搭建中如何配置自动生成API文档_接口规范化-ThinkPHP-PHP中文网

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环境搭建中如何配置自动生成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”，看不到具体字段。

btpanel phpsite 宝塔面板PHP网站

宝塔面板 PHP 网站管理：站点创建、删除、启停、PHP 版本切换、域名管理、SSL证书管理、伪静态管理、数据库管理

下载

必须补充 @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 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，基本就是上面两点没配对