ThinkPHP 6 的 @api 注解不生效是因为框架本身不解析 API 文档注解，需安装 zircote/swagger-php 扩展并严格遵循 OpenAPI 标准书写 @OA\Get 等注解，确保路径与路由注册一致且 JSON 文件可通过独立路由正确访问。
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。
立即学习“PHP免费学习笔记（深入）”；
/**
* @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") */
-
ref必须以#/components/schemas/xxx形式书写，大小写敏感 - 所有
@OA\Schema必须放在类、方法或文件顶部的 DocBlock 中，不能分散在多个注释块里 - 如果字段是「对象数组」，
@OA\Items里必须用ref，不能用内联@OA\Schema，否则生成器会丢弃 - TP6 的
validate规则（如array|require）不会自动转成 OpenAPI schema，必须手动补全
生成 OpenAPI 文档真正卡点不在语法，而在“路由路径一致性”和“静态资源可访问性”。很多人花半天调注解格式，最后发现是 Nginx 把 .json 当作动态请求转发给了 index.php。
