用途:该技能用于设计并编写符合 OpenAPI 3.x 规范的 API 规格文档,基于 RESTful 设计原则产出可维护的 API 定义、Schema 与文档。
主要能力:
- 端点设计与 Schema 定义,含认证授权配置、错误处理与文档生成;
- 提供基础模板(assets/openapi-base-template.yaml)与端点模板(assets/endpoint-template.yaml);
- 提供参考文档:references/basics.md(基本结构)、references/openapi-structure.md(各节规范)、references/schema-design-patterns.md(Schema 设计)、references/security-schemes.md(认证授权);
- 提供校验脚本 scripts/validate-openapi.mjs 做语法检查;
- 分三阶段流程:需求定义、规范设计、验证。
使用方法:按阶段参考对应文件——需求定义阶段查看 references/basics.md,规范设计阶段参考 agents/design-api.md 并基于模板编写,验证阶段参考 agents/validate-spec.md 并运行 scripts/validate-openapi.mjs。设计前应先确认端点数量、认证方式、速率限制,并判断是新建还是更新现有规范。
适用场景:新建或更新 OpenAPI 规范、设计端点与 Schema、排查 OpenAPI 语法错误、配置安全方案。
限制与注意:更新时需明确变更前后差异并检查是否破坏兼容性;安全方案应在设计阶段就纳入而非事后追加;避免跨端点 Schema 不一致、省略错误响应定义、required 字段含糊、硬编码安全配置;未经验证不要部署到生产环境。
其他:官方文本暂未提供;详细步骤请参考 references/ 目录;变更记录建议写入 CHANGELOG.md。