接口文档生成失败主因是注释未被工具识别：标签体系错用（如think-swagger需@apiparam，官方apidoc需@apiparams）、注释位置不当（须紧贴action方法无空行）、路由未显式绑定、嵌套参数未扁平化、多级命名空间未配置扫描路径。
接口描述缺失，核心原因是注释没被工具识别——不是没写，而是格式、位置或语义不符合所用工具的解析规则。ThinkPHP6本身不生成文档，所有“自动生成”都依赖工具链对注释的精准提取，错一点就丢字段。
检查注释是否用了正确的标签体系
不同工具认不同的注释语法，混用或误用直接导致字段消失：
- 用 think-swagger：必须用
@api、@apiParam、@apiSuccess等非标准标签；@param string $id这类原生 PHPDoc 完全无效 - 用 topthink/think-apidoc（官方生态）：必须用
@ApiParams、@ApiReturn，且每个参数要显式写name="xxx"、type="string"、required=true；漏掉任一属性，该字段就不进文档 - 用 zircote/swagger-php：必须用
@OA\Get、@OA\Parameter等 OpenAPI 规范注解；@param或@apiParam都会被忽略
确认注释紧贴方法且无空行干扰
所有主流工具都要求注释块与控制器方法之间不能有空行，且必须包裹在实际执行的 action 方法上（不是父类同名方法）：
- 错误写法：
/** @apiParam ... */\n\npublic function index() { ... }（中间空行） - 错误写法：注释写在基类方法上，而子类重写了该方法但没加注释
- 正确写法：注释块最后一行紧挨着
public function index()，中间无换行
验证路由是否显式绑定到该方法
工具只扫描被 Route::get/post/... 显式指向的控制器方法，以下情况会导致整个接口不进文档：
-
Route::resource('user', 'UserController')—— 没加->only(['index'])，工具无法确定哪些方法被启用 -
Route::post('api/login', function () { ... })—— 闭包不解析注释 - 使用了中间件统一处理（如权限校验），但路由未指向具体 controller/action
- 多级命名空间（如
api\v2\UserController）未在工具配置中加入扫描路径
排查嵌套参数和数组字段写法
泛型注释一律失效，嵌套结构必须扁平化展开：
-
@param array $data→ 字段直接消失，不解析 -
@param string $user_name、@param int $user_age→ 正确 - 表单嵌套如
user[profile][avatar]→ 必须写成@param string $user_profile_avatar - think-swagger 中必填字段还需额外加
@required（非 PHPDoc 标准，但必须）
不复杂但容易忽略
大量免费API接口：立即使用
涵盖生活服务API、金融科技API、企业工商API、等相关的API接口服务。免费API接口可安全、合规地连接上下游，为数据API应用能力赋能！
