ThinkPHP如何做API文档自动生成_ThinkPHP注解解析详解【详解】-ThinkPHP-PHP中文网

thinkphp 6 的 @api 注解不生效是因为框架本身不解析 api 文档注解，需安装 zircote/swagger-php 扩展并严格遵循 openapi 标准书写 @oa\get 等注解，确保路径与路由注册一致且 json 文件可通过独立路由正确访问。

thinkphp如何做api文档自动生成_thinkphp注解解析详解【详解】

ThinkPHP 6 的 `@api` 注解不生效？先确认是否装了正确扩展

ThinkPHP 官方本身不解析任何 API 文档注解，@api、@param、@return 这类写法不会被框架自动识别或渲染。所谓“自动生成文档”，实际依赖第三方工具，最常用的是 zircote/swagger-php（即 Swagger-PHP）配合 ThinkPHP 路由导出规范 JSON。

常见错误是直接在控制器方法上写 @api，结果生成空文档或报错——因为 TP6 没有内置该注解处理器。

必须安装 composer require zircote/swagger-php
确保 PHP 版本 ≥ 7.4（Swagger-PHP 4.x 要求）
注解必须写在 /** */ 块中，且紧贴控制器方法上方（不能隔行或被其他注释打断）
不要混用 ThinkPHP 5.1 时代的 think-apidoc 插件，它不兼容 TP6+（已停止维护）

用 `@OA\Get` 写接口定义时，`path` 必须和路由注册一致

Swagger-PHP 使用 OpenAPI 标准，所有接口需显式声明 @OA\Get、@OA\Post 等，其中 path 参数不是控制器路径，而是你通过 Route::get() 实际注册的 URL 路径。

例如你注册了 Route::get('api/v1/users', 'UserController@index');，那么注解里必须写 path="/api/v1/users"，而不是 /users 或 /index。

btpanel phpsite 宝塔面板PHP网站

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

下载

/**
 * @OA\Get(
 *   path="/api/v1/users",
 *   summary="获取用户列表",
 *   @OA\Response(response="200", description="OK")
 * )
 */
public function index()
{
    return json(['data' => []]);
}

路径开头带 /，否则 Swagger UI 会拼接错误 base_url
如果用了多级子域名或 API 网关前缀（如 https://api.example.com），需在生成器中单独配置 host 和 schemes，不能只靠注解
@OA\Parameter 中的 in 字段必须明确是 query、path、header 或 cookie，写成 url 或 get 会静默忽略

生成 JSON 后，前端 Swagger UI 打不开？检查响应头和静态服务

生成的 openapi.json 是纯静态文件，但 ThinkPHP 默认路由会拦截所有未匹配路径。如果你把 JSON 放在 public/api-docs/openapi.json，直接访问 /api-docs/openapi.json 很可能返回 404 或 HTML 页面。

推荐做法：用独立路由透传 JSON，例如在 app/route/app.php 加一行：Route::get('api-docs/openapi.json', function () { return file_get_contents(public_path() . '/api-docs/openapi.json'); });
必须设置响应头 Content-Type: application/json，否则 Swagger UI 会解析失败（可加 ->header('Content-Type', 'application/json')）
不要用 json() 返回该文件——它会二次 encode，导致 JSON 嵌套损坏
本地调试时，用 php -S localhost:8000 -t public 启动服务器，比 Apache/Nginx 更容易验证静态路径是否可达

数组类型字段怎么写 `@OA\Schema`？别用 `type="array"` 硬套

Swagger-PHP 对数组嵌套支持较弱，直接写 @OA\Schema(type="array", items=@OA\Schema(type="string")) 可能无法正确渲染嵌套结构。更可靠的方式是定义一个独立 schema 引用。

/**
 * @OA\Schema(schema="UserListResult", type="object")
 * @OA\Property(property="data", type="array", @OA\Items(ref="#/components/schemas/User"))
 * @OA\Property(property="total", type="integer")
 *
 * @OA\Schema(schema="User", type="object")
 * @OA\Property(property="id", type="integer")
 * @OA\Property(property="name", type="string")
 */