用途
API Documenter 是一个专注于使用 OpenAPI/Swagger 规范创建完整 API 文档的技能。它适用于为 REST 或 GraphQL API 编写文档的场景。
激活时机
当出现以下情况时该技能会被激活：
- 要求记录某个 API
- 创建 OpenAPI/Swagger 规范
- 需要 API 参考文档
- 提到“API docs”
主要能力
OpenAPI 规范结构
技能提供 OpenAPI 3.0.3 的规范结构示例，包含 info、servers、paths、components 等顶层字段，以及路径、操作、响应和 Schema 的写法。
端点文档
针对每个端点，技能区分必填字段与推荐字段。
必填字段：
- summary：简要描述
- operationId：唯一标识符
- description：详细说明
- tags：用于分组
- responses：所有可能的响应
推荐字段：
- parameters：所有参数及其细节
- requestBody：用于 POST/PUT/PATCH
- security：认证要求
- deprecated：如适用
技能给出 /users/{id} 的 GET 端点示例，展示 summary、operationId、description、tags、parameters、responses（含 200 与 404）的写法。
Schema 文档最佳实践
- 对共享 Schema 使用引用
- 为所有属性添加描述
- 为字符串指定格式（email、uuid、date-time）
- 为复杂 Schema 添加示例
- 标记必填字段
技能给出 User Schema 示例，包含 required、properties、format、description、example 等字段。
认证文档
技能说明如何记录认证要求，给出 security 与 components.securitySchemes 的示例，其中 bearerAuth 使用 http、bearer、JWT 格式，并说明使用来自 /auth/login 的 JWT 令牌。
错误响应
技能提供标准错误格式的 Schema 示例，包含 error、code、details 字段，并列出常见 HTTP 状态码：200、201、204、400、401、403、404、409、422、500。
使用方式
技能附带脚本命令：
从代码生成 OpenAPI 规范：
python3 scripts/generate_openapi.py --name <resource-name> --output openapi.yaml
校验 OpenAPI 规范：
python3 scripts/validate_openapi.py --input openapi.yaml
参考资料
- references/openapi-template.yaml - OpenAPI 模板
- references/examples/ - API 文档示例
适用场景
适用于需要为 REST 或 GraphQL API 编写 OpenAPI/Swagger 规范、API 参考文档、端点说明、Schema 定义、认证与错误响应文档的开发与文档工作。
限制
资料未提供该技能的具体平台支持范围、收费方式、价格、实际使用效果等信息，暂未提供。