PHP项目应使用注解（如zircote/swagger-php）自动生成OpenAPI文档，注解须写在可自动加载的类/方法中，严格遵循OpenAPI v3规范定义请求体、响应体及MIME类型，并通过PHP路由动态输出JSON以适配Swagger UI或Redoc。
PHP 项目里手写接口文档太容易过期，用注释自动生成是可行的，但关键在于选对工具链和规范注释格式——否则生成的 Markdown 不仅难读，还常漏参数、错类型。
用 phpDocumentor 生成基础结构，但得重写模板
phpDocumentor 默认输出 HTML，不直接支持 Markdown；强行导出再转换会丢结构。实际做法是用它解析注释 AST，再自己渲染：
- 安装时加
--with-all-dependencies避免插件加载失败 - 必须启用
@api、@endpoint、@method等自定义标签，原生@param只能描述变量，不能表达 HTTP 参数位置（query/path/body） - 模板里要识别
@example块并转成```json代码块，否则示例缩进全乱
注释里必须区分参数来源，否则生成的请求示例不可用
同一个 $id 可能是 URL path 参数、query 字符串或 JSON body 字段，生成文档时若不显式声明，Markdown 表格里就只写“int”，根本没法调用：
Telegram Markdown Adapter
下载
将 Markdown 格式的回复转换为适合 Telegram 的富文本，避免渲染错误。适用于用户偏好 Markdown 但目标平台为 Telegram 的场景。
- 统一用
@pathParam $id int "用户ID"标记路径参数 -
@queryParam page int "页码" [1]支持默认值标注，方括号内容会被提取进“默认值”列 -
@bodyParam name string "用户名" required中的required触发必填标记 - 不写来源标记的
@param会被忽略——这是防止旧注释污染新文档的关键开关
生成命令要绑定路由扫描，不能只扫 Controller 文件
只解析类文件会漏掉闭包路由、中间件注入的参数，也识别不了 Laravel 的 Route::apiResource() 自动注册规则：
立即学习“PHP免费学习笔记（深入）”；
- 先用
php artisan route:list --format=json导出路由清单，提取action['controller']和method - 再反查对应方法的 PHPDoc，把
GET /users/{id}和UsersController@show关联起来 - 对无控制器的闭包路由，要求强制写
@route GET /hook/callback注释，否则跳过生成 - 生成脚本里加
--strict模式：任何没匹配到路由的 API 注释都报 warning，避免文档“存在但不可达”
最难的不是生成 Markdown，而是让所有人写注释时不偷懒——比如忘记标 @bodyParam 类型，或把 required 写成 require，这种拼写错误会导致字段直接消失。上线前最好加个 CI 检查，用正则扫所有 @(path|query|body)Param 后是否跟了类型声明。
