ApiDoc（gen:apidoc）

扫描应用 Router 下的路由定义，结合 Controller action、BaseRequest / BaseResponse 与注解，生成 OpenAPI 3.0 YAML。可用仓库内 swaggerui/（Swagger UI）浏览输出文件。

php script.php start App --c=gen:apidoc
php script.php start App --c=gen:apidoc --router=App/Router --out=swaggerui/apidoc

输出：swaggerui/apidoc/openapi-{module}.yaml（每次生成前清理同目录旧 openapi-*.yaml）。

---

模块 title / description

优先级（高 → 低）：

1. Router/api_router_module.json 中该模块的 title / description
2. 应用 Config/apidoc.php（可选，见 stub）的全局 title / description / version
3. 默认：title = {AppName} · {Module}，description = Generated by swoolefy gen:apidoc

{
  "Product": {
    "title": "用户产品中心",
    "description": "用户产品模块"
  }
}

---

Operation 文案瀑布

优先级	summary	description
1	#[ApiOperation(summary: '...')]	#[ApiOperation(description: '...')]（与 summary 不同时才写入）
2	仅写了 description 时，用作 summary（不再复制到 description）	—
3	PHPDoc 首行有效文本	—
4	{METHOD} {path}	—
5	action 方法名	—

兼容写法：

#[ApiOperation(description: '创建用户')]           // → summary
#[ApiOperation(summary: '创建用户', description: '需管理员权限')]  // 二者分开
#[ApiOperation('创建用户')]                      // 位置参数 → description → 作 summary

---

请求体 vs Query

HTTP 方法	BaseRequest 参数在 OpenAPI 中的位置
GET / HEAD / DELETE	query parameters（按 DTO 顶层属性展开）
POST / PUT / PATCH 等	requestBody application/json

标量 action 参数（非 BaseRequest）始终为 query。

嵌套对象在 query 中的表达能力有限；复杂筛选建议拆成标量字段，或改用 POST + body。

---

默认 responses

每个 operation 至少包含：

状态码	含义
200	成功信封 {code,msg,trace_id,data}
400	参数校验失败（同信封，code 示例非 0）

若路由块（含所在 Route::group 的 middleware）检测到：

• AuthenticateMiddleware / OptionalAuthenticateMiddleware / beforeHandle 鉴权 → 增加 401
• ApiRateLimiterMiddleware / ApiUserRateLimiterMiddleware / withRateLimiterMiddleware → 增加 429

---

相关文件

• 生成器：ApiDocGenerator.php
• 命令：Swoolefy\Script\GenerateApiDoc
• 配置模版：src/Stubs/apidoc.conf.stub.php → 应用 Config/apidoc.php
• 主文档：仓库根 README.md §十九
• 入参基类：Swoolefy\Http\BaseRequest（含 validated() 等读参助手）