ThinkPHP6接口文档生成失败的核心原因是注释格式、swagger-php版本与路由配置三者未对齐。需锁定安装v3.4.1版本，注解须严格紧贴方法且path与路由完全一致，路由须显式注册，扫描路径需精准限定控制器目录。
ThinkPHP6 接口文档生成失败，核心问题通常不是“没装工具”，而是注释、工具版本、路由三者没对齐。只要其中一环出错，就会出现空 JSON、404 页面、字段缺失或路径不显示。
确认用对了 swagger-php 版本
最新版 swagger-php v4+ 要求 PHP 8.1+，而 TP6 多数运行在 PHP 7.3–8.0 环境下，直接 composer require zircote/swagger-php 会拉到 v4，导致解析中断、@OA\Get 报错、返回空或 500。
- 必须锁定安装 v3.4.1：
composer require zircote/swagger-php:3.4.1 - 别用
3.*，它可能装到不稳定的 3.5.x - v3.4.1 兼容 TP6 的 AST 解析逻辑，能正确识别
@OA\Get、@OA\Post等注解
检查注释写法和位置是否规范
TP6 不吃“看起来像注释”的内容，只认严格格式的 OpenAPI 注解，且必须紧贴方法声明，中间不能有空行。
- 注解必须写在控制器方法正上方，例如：
/** @OA\Get(path="/api/user", summary="获取用户列表") */
public function index() { ... } -
path值必须与路由注册的完整 URL 完全一致，包括开头的/和前缀（如/api/user，不能是api/user或/user） - 确保控制器类在 Composer 自动加载范围内（如
app/controller/），并在composer.json中配置了 PSR-4 映射
验证路由是否被工具扫描到
swagger-php v3 不会自动识别所有 public 方法，它只扫描被显式注册到路由的控制器动作。
立即学习“PHP免费学习笔记（深入）”；
- ❌ 错误写法：
Route::resource('user', 'UserController');（未加only，部分方法不会进路由表） - ✅ 正确写法：
Route::get('api/user', 'UserController@index');或Route::resource('user', 'UserController')->only(['index', 'store']); - 调试时先执行
php think route:list，确认目标接口出现在列表中，且 HTTP 方法和路径完全匹配 - 扫描路径要精确：只扫
app/controller/和app/api/，排除middleware、model等非控制器目录，避免因解析失败中断
用 think-apidoc 时注意标签和结构
如果选的是官方轻量方案 topthink/think-apidoc，它完全不识别标准 PHPDoc，只认 @ApiXXX 标签。
- 必须写全
@ApiParams四个属性：name、type、required、description，漏一个就丢参数 -
type只支持string/integer/boolean/array，写int或bool会被跳过 - 嵌套字段（如
user[profile][avatar]）要扁平化：@ApiParams(name="user_profile_avatar", type="string", ...) -
@ApiReturn必须写具体 JSON 结构，不能只写array；否则前端看不到响应字段
