ThinkPHP自动生成API文档方法-ThinkPHP-PHP中文网

thinkphp 自动生成api文档需工具、注释、路由三者协同；think-swagger要求显式路由与扁平化字段注释，topthink/think-apidoc需专用标签，zircote/swagger-php需openapi规范注解，所有工具均不分析运行时返回值。

thinkphp自动生成api文档方法

ThinkPHP 本身不生成 API 文档，所有“自动生成”都依赖你选对工具、写对注释、配对路由——三者缺一不可。装完扩展就指望 php think api 命令吐出一份完整 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 包含该目录

这是 ThinkPHP6 官方生态方案，不用 OpenAPI 规范，但标签不能混用：必须用 @ApiParams、@ApiReturn，不能夹带 @param 或 @OA\Get。

laravel-specialist

精通 Laravel 10+，遵循现代 PHP 实践的 Laravel 专家。擅长优雅语法、Eloquent ORM、队列系统及企业级特性...

下载

@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，文档里就不会标必填

如果你项目已对接外部平台，或需要机器可读的 JSON/YAML，这是更通用的选择。但它不认 @param，必须写 @OA\Get、@OA\Parameter 等结构化注解。

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 补全的 @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 并在描述中说明