TP6接口Swagger文档生成的实现-ThinkPHP-PHP中文网

tp6 自动生成api文档依赖zircote/swagger-php v3.4.1解析@oa注解，需严格规范注解格式、路径配置及扫描范围，并配合swagger ui展示；v4不兼容php

tp6接口swagger文档生成的实现

TP6 本身不解析任何 API 注释，所谓“自动生成文档”其实是靠外部工具 zircote/swagger-php 解析 OpenAPI 标准注解（如 @OA\Get），再导出 JSON，最后用 Swagger UI 渲染。关键不在框架，而在注解写法、工具版本和路径配置是否精准。

必须锁定 swagger-php v3.4.1

最新版 swagger-php v4 要求 PHP 8.1+，且重构了注解扫描逻辑，与 TP6（通常运行于 PHP 7.3–8.0）不兼容。强行安装会导致：

Fatal error: Uncaught TypeError: OpenApi\Annotations\OpenApi::__construct()
Class "OpenApi\Annotations\Get" not found
生成空 JSON 或 500 错误，无明确提示

正确做法是强制指定稳定版本：

composer require zircote/swagger-php:3.4.1

不要写 3.* —— 它可能拉到 3.5.x，已开始引入 v4 兼容行为，TP6 下同样不可靠。

注解写法必须严格规范

Swagger-PHP v3 只认 @OA\* 注解，且对格式极其敏感：

小绿鲸

小绿鲸是一款AI论文写作工具，AI英文文献阅读工具。

下载

必须写在 /** */ 块中，紧贴控制器方法上方，中间不能有空行
必须声明命名空间：use OpenApi\Annotations as OA;
@OA\Get 的 path 必须与 Route::get() 注册的 URL 完全一致（含开头斜杠、不含多余结尾斜杠）
例如路由是 Route::get('api/v1/users', 'UserController@index')，注解必须写 path="/api/v1/users"，而不是 /users、api/v1/users 或 /api/v1/users/
带参数的路径如 Route::get('api/v1/users/{id}')，注解中写 path="/api/v1/users/{id}"，并额外加 @OA\Parameter 描述变量

路由中安全生成 openapi.json

不能直接扫描整个 app/ 目录 —— 里面混有 middleware、model、provider 等非控制器文件，v3 版本遇到语法异常会直接中断，返回空或崩溃。

推荐在 route/app.php 中定义一个专用路由，显式限定路径并排除干扰：

示例：

Route::get('/swagger', function () {
  try {
    $openapi = \OpenApi\scan([
      app_path('controller'),
      app_path('api') // 如有独立 api 目录
    ], [
      'exclude' => [
        app_path('middleware'),
        app_path('model'),
        app_path('controller/BaseController.php')
      ]
    ]);
    header('Content-Type: application/json; charset=utf-8');
    echo $openapi->toJson();
  } catch (\Exception $e) {
    http_response_code(500);
    echo json_encode(['error' => $e->getMessage()]);
  }
});