ThinkPHP8授权接口文档需体现认证方式、权限标识、访问限制说明三要素：用OA\SecurityScheme定义认证方案，@Permission注解同步权限码至x-permission字段，中间件校验逻辑对应写入401/403/422状态码说明。
ThinkPHP8 添加授权接口文档，核心是把权限控制逻辑和接口描述统一起来，让文档能真实反映“谁能在什么条件下访问哪个接口”。不能只写 Swagger 注释却不校验权限，也不能只写中间件却不在文档中标明认证要求。
授权接口文档必须体现三个关键点：认证方式、权限标识、访问限制说明。
授权方式要在接口文档中明确标注
Swagger-php 5.x 不再默认解析 PHPDoc，改用 PHP 属性注解，所以需在控制器方法上显式声明安全方案：
#[OA\Get(
path: '/api/v1/user/profile',
summary: '获取用户个人信息',
security: [['bearerAuth' => []]], // 表示需要 Bearer Token
)]
#[OA\SecurityScheme(
securityScheme: 'bearerAuth',
type: 'http',
scheme: 'bearer',
bearerFormat: 'JWT'
)]注意：security 字段必须与 SecurityScheme 的 securityScheme 名称一致；多个接口共用时，建议在类级或全局定义一次 SecurityScheme，避免重复。
立即学习“PHP免费学习笔记（深入）”；
权限标识要通过自定义注解同步到文档中
ThinkPHP 8 的 @Middleware 注解本身不传递权限码，但你可以用 think-annotation 扩展定义 @Permission 注解，并在生成文档时读取它：
#[Permission('user:profile:read')]
public function profile()
{
return json(['data' => $this->auth->user()]);
}然后在 Swagger 文档生成脚本中，通过反射提取该注解值，注入到 description 或 x-permission 扩展字段里（Swagger 支持自定义字段）：
#[OA\Get(
description: "需要权限：user:profile:read",
x: ['permission' => 'user:profile:read'],
)]这样前端或测试人员一眼就能看到调用该接口所需的最小权限。
访问限制说明要结合中间件行为写进文档
比如你的 JWT 中间件做了以下判断：
- token 过期自动拒绝
- role 为
guest时禁止访问/user/profile - 某些接口还要求
scope=profile_read
这些不能只藏在中间件代码里，得在文档的「认证说明」或「响应状态码」部分体现：
-
401 Unauthorized：Token 缺失、格式错误或已过期 -
403 Forbidden：Token 有效但无对应权限（如缺少user:profile:read）或 scope 不匹配 -
422 Unprocessable Content：refresh_token 失效且无法静默刷新（适用于带自动续期逻辑的授权流程）
实际写文档时，在接口下方加一段「授权说明」小节即可：
#[OA\Get(
description: '获取用户个人信息（需登录且具备 user:profile:read 权限）',
)]这样既保持 Swagger 自动生成能力，又让权限约束可读、可测、可维护。
