apidoc无法解析Yii控制器是因为其仅识别含@api等标记的类C风格注释，而Yii的action方法默认无此类注释，且不分析路由、behaviors或REST映射。
apidoc 不能直接解析 Yii 框架的 PHP 控制器代码生成文档——它只认 JavaScript、Java、PHP（但仅支持特定注释风格）、C#、Go 等语言的“类 C 风格注释”，而 Yii 的 Controller 方法通常不写 /** @api ... */ 这类 apidoc 要求的结构化注释，直接跑 apidoc -i ./controllers -o ./doc 会生成空文档或大量警告。
为什么 apidoc 扫不到 Yii 的 action 方法
apidoc 的解析器依赖显式的 @api、@apiName、@apiGroup 等标记，且要求这些注释紧贴在函数声明上方；Yii 的 actionXXX() 是普通 public 方法，没有默认注释，即使你写了 PHPDoc，只要没带 @api 前缀，就完全被忽略。它不分析路由配置（如 urlManager 规则）、不读取 behaviors() 或 verbs()，也不理解 RESTful 模式下的自动动词映射。
常见错误现象：error: No API found. Please add at least one @api to your source code. 或生成的 index.html 里只有 “No APIs found”。
- Yii 2.x 的
ActiveController自动绑定GET /items→actionIndex()，但 apidoc 不知道这层映射 - 你写了
/** @return array */，但缺@api，apidoc 当作普通注释跳过 - 使用了
yii\rest\Controller+yii\filters\VerbFilter控制权限，apidoc 完全不可见
怎么让 apidoc 正确识别 Yii 接口
必须手动在每个要暴露的 action 方法上方，补全 apidoc 要求的注释块，并严格对齐其语法。不是“补充说明”，而是“重写接口契约”。
实操建议：
- 在
actionIndex()上方写完整/** @api {get} /v1/users List users */，路径用实际路由，不是控制器类名 -
@apiParam和@apiSuccess中的字段名，要和你ActiveRecord::fields()或toArray()返回结构一致，别照抄数据库字段 - 如果接口有认证，加
@apiHeader {String} Authorization Bearer <token>，别写成@apiParam - 避免在注释里写动态内容，比如
@apiSuccessExample {json} Success-Response: <%= JSON.stringify($data) %>—— apidoc 不执行 JS，会原样输出
示例（放在 controllers/UserController.php 的 actionView() 上方）：
/**
* @api {get} /v1/users/:id Get user by ID
* @apiName GetUser
* @apiGroup User
* @apiVersion 1.0.0
* @apiParam {Number} id User unique ID
* @apiSuccess {Number} id
* @apiSuccess {String} username
* @apiSuccess {String} email
* @apiSuccessExample {json} Success-Response:
* HTTP/1.1 200 OK
* {
* "id": 1,
* "username": "admin",
* "email": "admin@example.com"
* }
*/
public function actionView($id)
{
return $this->findModel($id);
}比 apidoc 更适合 Yii 的替代方案
硬套 apidoc 成本高、易脱节：每次改 action 名、参数或返回结构，都得同步改注释，漏改就导致文档和实际不符。更务实的做法是换工具链。
推荐路径：
- 用
zircote/swagger-php+swagger-ui：Yii 项目中可配合yii2-swagger扩展，在控制器方法上写@OA\Get等 OpenAPI 注解，支持从ActiveRecord::fields()自动推导响应结构 - 用
linslin/yii2-curl+ 自定义命令脚本：调用真实接口，抓 response schema，生成 JSON Schema 文档（适合已有稳定测试环境） - 放弃自动生成，用
Postman Collection + Postman Docs：人工维护请求示例，导出为静态页，更新成本低，前端联调也直接能 import
关键区别：swagger-php 注解是 PHP 代码的一部分，IDE 可检查、Git 可追踪、CI 可校验；而 apidoc 注释是“伪代码”，没人维护就迅速过期。
最常被忽略的一点：文档不是写给机器看的，是写给人看的。与其花半天调通 apidoc 的 --debug 输出，不如把 @apiSuccess 字段名改成前端真正接收的 key，哪怕多打两行字。
