ThinkPHP 8.0 基于 OpenAPI 3.0 规范自动生成接口文档【Swagger】

先说几个关键点：ThinkPHP 8.0 本身不内置文档生成能力，要基于 OpenAPI 3.0 规范自动生成接口文档，必须靠注解 + 工具链 + 路由三者严格对齐。不是装个包就能跑通，关键在细节是否到位。

注解必须写对、位置不能错

Swagger-PHP（zircote/swagger-php）只扫描 /** @OAGet() */ 这类标准 OpenAPI 注解，且必须紧贴控制器 public 方法上方，中间不能有空行或其它注释干扰。

• 必须加命名空间声明：use OpenApiAnnotations as OA;
• @OAGet、@OAPost 等必须写在具体 action 方法上，不能只写在类顶部
• path="/api/v1/users" 必须和 Route::get('api/v1/users', ...) 中注册的完整路径完全一致（开头带 /，含前缀与版本号）
• 参数不能靠函数签名推断：public function show($id) 不会自动变成 id 查询参数，得显式写：

  @OAParameter(name="id", in="path", required=true, @OASchema(type="integer"))

• 请求体必须用 @OARequestBody + @OAJsonContent 描述，光写 @OAProperty 不生效

生成命令和输出路径要精准

运行命令时路径错一个字母，就可能漏掉全部接口：

php -d memory_limit=-1 vendor/bin/openapi app/controller/ -o public/swagger.json

• 输入路径 app/controller/ 必须真实存在且被 Composer 自动加载（检查 composer.json 的 autoload.psr-4）
• 输出路径 public/swagger.json 必须能被 Web 服务器直接访问（如 http://localhost/swagger.json），Nginx/Apache 不能拦截 .json 后缀
• 若用多应用或多级命名空间（如 apiv2UserController），需确认扫描路径覆盖到对应目录

Swagger UI 能打开但“Try it out”失败？查 servers 和 header

页面加载成功但测试报 404 或 CORS，大概率是：

• openapi.json 缺少全局 servers 字段 → 必须在某处（如控制器类或方法注释块里）加：

  @OAInfo(    title="API 文档",    version="1.0.0",    @OAServer(url="http://localhost:8000/api"))

• 服务端响应没设正确 header → PHP 输出 JSON 前加：

  header('Content-Type: application/json; charset=utf-8');

• 若部署在子域名或网关后（如 https://api.example.com），@OAServer 的 url 需写完整地址，不能只写 /api

别踩这些高频坑

• 报错 Class 'OpenApiAnnotationsGet' not found → 检查是否漏装 openapi/openapi（v4+ 版本已拆分，zircote/swagger-php 单独装不够）
• 文档里参数全空 → @OAParameter 的 in 字段只能是 query、path、header、cookie，写成 url 或 get 会被静默忽略
• 中文注释导致 JSON 解析失败 → 避免全角标点（「」、【】、——），统一用英文引号和破折号
• 嵌套结构描述错误 → @OAJsonContent 内部嵌套 @OAProperty 时，类型、示例、必填都得手动写全，不能省略

不复杂但容易忽略。