thinkphp接口文档生成必须同时满足明确注释（@apixxx标签）、正确工具（think-apidoc）和严格路由绑定（显式注册），缺一则导致字段缺失、路径错乱或必填项不标；@apiparams须写全name/type/required/description四属性，type仅支持string/integer/boolean/array等基础类型，嵌套字段需扁平化命名；路由必须显式声明（如route::post），不可依赖route::resource()自动推断；@apiroute路径须与实际路由完全一致（含斜杠和大小写）；@apireturn必须提供具体json结构而非仅array；扫描路径需在配置或命令中显式指定（如--module v2），否则代码不被识别。
ThinkPHP 接口文档不能靠“写完控制器自动出”，必须配合明确注释 + 正确工具 + 严格路由绑定，三者缺一不可。否则生成的文档字段缺失、路径错乱、必填项不标，前端联调时直接卡死。
think-apidoc 注释格式必须用 @ApiXXX 标签，不能混用 @param
topthink/think-apidoc 是 ThinkPHP6 官方生态推荐的轻量方案，它只识别 @ApiTitle、@ApiParams、@ApiReturn 等自定义标签，完全忽略标准 PHPDoc 的 @param 或 @return。
-
@ApiParams必须写全四个属性：name、type、required、description，漏一个就无法解析该参数 -
type只接受string、integer、boolean、array等基础类型，写int或bool可能被跳过 - 嵌套字段如
user[profile][avatar]要拆成独立参数：@ApiParams(name="user_profile_avatar", type="string", required=false, description="用户头像URL") - 如果控制器方法没加
@ApiMethod，默认当成GET处理，POST/PUT 接口会显示错误请求方式
路由必须显式注册，resource 路由要加 only/except 限定
think-apidoc 不扫描未注册的控制器方法，也不推断 Route::resource() 自动生成的路径 —— 它只认 route/app.php 或 route/api.php 中明确写出的路由条目。
- ✅ 正确：
Route::post('api/v1/user', 'api.v1.UserController/store');（显式指向具体方法） - ❌ 错误：
Route::resource('user', 'api.v1.UserController');（不加only会导致部分方法未注册，文档里找不到） - 路径含版本号（如
api/v1/）时，@ApiRoute注释必须严格匹配：@ApiRoute("/api/v1/user")，少个斜杠或大小写错都会导致文档路径为空 - 调试时运行
php think route:list，确认目标方法确实出现在列表中，且 HTTP 方法和路径完全一致
@ApiReturn 和 @response 必须写具体结构，不能只写 array
think-apidoc 不执行控制器逻辑，也不反射返回值结构，它只按字面解析 @ApiReturn 或 @response 标签内容。写 @ApiReturn array 文档里只会显示 “array”，前端看不到任何字段。
- 必须提供完整 JSON 示例：
@ApiReturn {"code":200,"msg":"ok","data":{"id":1,"name":"test"}} - 若返回结构统一（如都包在
{"code":...,"data":...}里），建议在基类控制器写好通用模板，子类用@see引用，避免每个方法重复写 - 数组元素类型混合（如
["name", 123, true]）时，不要写string|int|boolean[]，应统一标为array并在description里说明：“数组，元素依次为用户名（字符串）、用户ID（整型）、是否激活（布尔）” - 响应中的枚举字段（如
status只能是"active"/"inactive"）必须在description明确列出，不能只写“状态”
最常被忽略的是：注释写了，路由也配了，但控制器命名空间目录没被 think-apidoc 扫描到 —— 比如用了 app/api/v2/ 目录，却没在生成命令里指定 --module v2，或者配置里没把该路径加入 scan_paths。这时候文档页面空空如也，不是工具坏了，是它根本没看到你的代码。
php免费学习视频：立即使用
踏上前端学习之旅，开启通往精通之路！从前端基础到项目实战，循序渐进，一步一个脚印，迈向巅峰！
