thinkphp本身不生成api文档，必须依赖正确注释、选定工具（如think-swagger或zircote/swagger-php）及显式路由绑定三者协同；缺一即导致空文档、404或字段缺失。
ThinkPHP 本身不生成接口文档，所有“自动生成”都依赖你写对注释 + 选对工具 + 配对路由。没这三步，php think apidoc 或 swagger-php 都会输出空 JSON、404 页面，或字段全丢。
为什么 swagger.json 里没有你的接口？
think-swagger 和 zircote/swagger-php 都只扫描被显式路由绑定的控制器方法，不是“所有 public 方法”都会进文档。
- ✅ 正确：Route::get('api/users', 'api.UserController@index');
- ❌ 错误：Route::resource('users', 'UserController');（没加
only限定） - ❌ 错误：Route::post('api/login', function () { ... });（闭包不解析注释）
- 如果用了多级命名空间如
api\v2\UserController，确认工具配置里的paths包含该目录，否则直接跳过
@param array $data 为什么文档里字段全没了？
think-swagger 不识别泛型数组注释，也不会递归展开结构；zircote/swagger-php 要求用 @OA\Parameter 显式声明每个字段。两者都不吃 IDE 自动生成的 @param array。
- ❌
@param array $user→ 字段消失 - ✅
@param string $user_name、@param int $user_age - 嵌套参数如
user[profile][avatar]，必须写成@param string $user_profile_avatar - think-swagger 必须加
@required（非标准 PHPDoc），否则即使验证器写了'id|require'，文档也不标必填
用 zircote/swagger-php 时 path 总错，怎么对齐？
@OA\Get 的 path 值不是控制器方法名，也不是路由定义里的相对路径片段，而是你通过 Route::get() 注册的完整 URL 路径，且必须带开头 /。
- 你注册的是：
Route::get('api/v1/users', 'UserController@index'); - 注解里必须写：
path="/api/v1/users"（不能是/users、api/v1/users或/index） - 如果 API 部署在子域名或网关后（如
https://api.example.com），@OA\Info里要单独配host="api.example.com"和schemes={"https"}，光靠注解里的path拼不出正确请求地址
生成的 openapi.json 访问 404 怎么办？
ThinkPHP 默认路由会拦截所有未匹配路径，public/api-docs/openapi.json 是静态文件，但直接访问 /api-docs/openapi.json 会被框架当成未定义路由，返回 404 或首页 HTML。
- 别把 JSON 放 public 下就完事——得加透传路由：
- 在
app/route/app.php加一行：Route::get('api-docs/openapi.json', function () { return file_get_contents(public_path() . '/api-docs/openapi.json'); }); - 确保响应头是
Content-Type: application/json，否则 Swagger UI 加载失败 - 如果用了 Nginx，检查是否误配了
try_files规则，导致所有路径都被重写到index.php
最常被忽略的点：注释和验证逻辑脱节。你在 @param int $id 里写了类型，但控制器没做 intval() 或断言；你在验证器里写了 'id|number|require'，但注释漏了 @required——这些都会让文档和实际行为不一致，而工具不会报错，只会静默按注释生成。
php免费学习视频：立即使用
踏上前端学习之旅，开启通往精通之路！从前端基础到项目实战，循序渐进，一步一个脚印，迈向巅峰！
