swagger-php v4在tp6中无法运行，因其要求php 8.1+并重构注解扫描机制，而tp6依赖v3的ast解析规则；必须锁定安装v3.4.1版本，并限定扫描路径、排除非控制器目录，同时确保@oa\info等注解规范书写。
swagger-php 是当前 ThinkPHP6 项目中实现接口文档自动化的主流选择，但直接 composer require zircote/swagger-php 安装最新版（v4+）会导致注解解析失败、@OA\Get 报错、路由无法识别等现象——必须锁定 v3.x 版本才能稳定工作。
为什么 swagger-php v4 在 TP6 里跑不起来？
ThinkPHP6 默认使用 PHP 7.3+，而 swagger-php v4 要求 PHP 8.1+ 并重构了注解扫描机制，废弃了 @SWG\ 前缀，改用 @OA\，但 TP6 的旧版扫描逻辑（如 OpenApi\scan()）仍依赖 v3 的 AST 解析规则。常见报错包括：
Fatal error: Uncaught TypeError: OpenApi\Annotations\OpenApi::__construct(): Argument #1 ($annotations) must be of type array, null givenClass "OpenApi\Annotations\Get" not found- 路由返回空 JSON 或 500 错误，但控制台无提示
解决办法只有一条：强制安装 v3.4.1：
composer require zircote/swagger-php:3.4.1
别用 3.*——它可能拉到 3.5.x，而 3.5.x 已开始兼容 v4 的部分行为，TP6 下同样不稳定。
如何让 /swagger 路由正确输出 OpenAPI JSON？
不能只靠 OpenApi\scan(root_path().'app') 扫描全部目录：TP6 的 app 目录下混有 middleware、model、provider 等非控制器代码，swagger-php v3 会因解析失败直接中断，导致返回空或报错。
推荐做法是明确限定扫描路径，并排除干扰项：
- 只扫描
app/controller和app/api（如有） - 在路由闭包中显式指定
exclude参数 - 加一层 try-catch 防止整个接口崩掉
示例路由（写在 route/app.php 中）：
Route::get('/swagger', function () {
try {
$openapi = \OpenApi\scan([
app_path('controller'),
app_path('api')
], [
'exclude' => [
app_path('controller/BaseController.php'),
app_path('middleware'),
app_path('model')
]
]);
header('Content-Type: application/json; charset=utf-8');
echo $openapi->toJson();
} catch (\Exception $e) {
http_response_code(500);
echo json_encode(['error' => $e->getMessage()]);
}
});
注解写在哪？哪些字段必须写？
注解必须写在控制器类或方法的 DocBlock 里，且类级 @OA\Info 必须存在，否则 v3 扫描器不会生成根信息，UI 会提示 “Failed to load spec.”。
最小可用结构如下（以 app/controller/User.php 为例）：
namespace app\controller; <p>use app\BaseController;</p><p>/**</p>
- @OA\Info(title="用户服务 API", version="1.0.0")
*/
class User extends BaseController
{
/**
- @OA\Get(
- path="/api/user/{id}",
- summary="获取单个用户",
- tags={"用户"},
- @OA\Parameter(name="id", in="path", required=true, @OA\Schema(type="integer")),
- @OA\Response(response="200", description="成功", @OA\JsonContent(
- @OA\Property(property="code", type="integer", example=200),
- @OA\Property(property="data", type="object",
- @OA\Property(property="id", type="integer"),
- @OA\Property(property="name", type="string")
- )
- ))
- )
*/
public function read($id)
{
return json(['code' => 200, 'data' => ['id' => $id, 'name' => 'test']]);
}
}
注意几个硬性要求：
-
@OA\Info必须出现在某个类或文件顶部，且全局唯一 -
path中的路径要和实际路由一致（TP6 的资源路由需手动对齐） -
@OA\Parameter的in值必须是path、query、header或formData，不能写url或body - 所有
@OA\注解必须成对出现，比如@OA\Response内嵌@OA\JsonContent，不能漏掉
-
前端 UI 怎么接上？别用官方 dist
Swagger UI 官方 dist 默认请求 /openapi.json，但你的 TP6 路由是 /swagger。直接放一个官方 index.html 过去，会 404。
最简方案：下载 Swagger UI 的预构建包（如 swagger-ui-dist@^4.15.5），然后在 TP6 的 public/dist 下放好，修改其 index.html 中的 url 配置：
const ui = SwaggerUIBundle({
url: "/swagger", // ← 改成你的路由
dom_id: '#swagger-ui',
deepLinking: true,
presets: [SwaggerUIBundle.presets.apis, SwaggerUIStandalonePreset],
plugins: [SwaggerUIBundle.plugins.DownloadUrl],
layout: "StandaloneLayout"
})
访问 http://your-domain.com/dist 即可看到可交互文档。不要试图用 php think apidoc 命令——那是 topthink/think-apidoc 插件的命令，和 swagger-php 无关，二者混用会导致注解冲突、重复生成、路径错乱。
真正容易被忽略的是：每次改完注解，必须清空 OPcache（如果启用）或重启 PHP-FPM，否则 scan() 可能读到旧的 AST 缓存，导致新增接口不显示。
php免费学习视频：立即使用
踏上前端学习之旅，开启通往精通之路！从前端基础到项目实战，循序渐进，一步一个脚印，迈向巅峰！
