能，但需借助think-swagger等第三方扩展并严格遵循Swagger语法注释：必须用@api、@apiParam等非标准PHPDoc标签，注释位置紧邻且无空行，路由须显式绑定，嵌套字段需拆解声明。
ThinkPHP 接口文档能靠注释自动生成吗？
能，但不是开箱即用。ThinkPHP 本身不内置接口文档生成器，必须借助第三方扩展（如 think-swagger 或 think-api-doc），且严重依赖规范的 PHPDoc 注释结构。没写对注释格式，生成结果就是空或错乱。
注释怎么写才被 think-swagger 识别
它只认特定标签，@api、@param、@return 这类不是标准 PHPDoc，而是 Swagger/OpenAPI 的扩展语法，得手动加。原生 /** @param string $id */ 不起作用。
-
@api {POST} /api/user/create 创建用户—— 必须有，定义路径和方法，缺了这行整个接口不进文档 -
@apiParam {string} username 用户名—— 类型必须小写，String或INT都会被忽略 -
@apiSuccess {object} data 返回数据结构—— 嵌套字段要用点号：data.token、data.profile.name - 控制器方法必须是
public，且路由需显式绑定（不能全靠 Route::rule 自动解析）
为什么生成的文档里没有参数或返回值
常见原因是注释位置或层级不对：@apiParam 必须紧贴在 @api 下方，中间不能插空行或其它标签；@apiSuccess 同理。另外，ThinkPHP 的自动路由（比如 Route::get('user/:id', 'index/user/info')）会导致路径解析失败，think-swagger 找不到对应方法。
- 检查生成命令输出是否有
Warning: method not found for route xxx - 把路由改写成闭包或显式绑定控制器方法：
Route::post('api/user', 'api.UserController/create') - 确保注释块包裹的是实际执行的 action 方法，不是父类里的同名方法
- 如果用了中间件做参数校验（如
Validate），think-swagger不会自动提取验证规则，得手写@apiParam
生成后页面打不开或 JSON 报错
多数是 Swagger UI 加载的 swagger.json 格式非法，根源常在中文注释里的全角标点、未转义的斜杠、或数组描述用了中文括号。
立即学习“PHP免费学习笔记（深入）”；
- 避免在
@apiDescription里用「」、【】、——，统一用英文引号和破折号 -
@apiParam {array} tags 标签列表后面不要跟(例: ["a","b"])，这种说明会被当 JSON 解析，导致语法错误 - 生成命令默认输出到
public/swagger.json，确认该路径 Nginx/Apache 有读取权限，且没被 rewrite 规则拦截 - 如果用了多模块，需在配置中指定扫描目录：
'scan_path' => [APP_PATH . 'api/controller/']
最麻烦的其实是嵌套响应体的类型声明——@apiSuccess {object} data.user 看似合理，但 think-swagger 不支持两级 key 的类型标注，得拆成 data 和 user 两个独立字段，否则 JSON Schema 会崩。
