SuperAPI AI 工具集

openapi-specification

编程与开发

查看项目

更新于 10-15 20:05

技能介绍

用途:该技能用于设计并编写符合 OpenAPI 3.x 规范的 API 规格文档,基于 RESTful 设计原则产出可维护的 API 定义、Schema 与文档。

主要能力:

  1. 端点设计与 Schema 定义,含认证授权配置、错误处理与文档生成;
  2. 提供基础模板(assets/openapi-base-template.yaml)与端点模板(assets/endpoint-template.yaml);
  3. 提供参考文档:references/basics.md(基本结构)、references/openapi-structure.md(各节规范)、references/schema-design-patterns.md(Schema 设计)、references/security-schemes.md(认证授权);
  4. 提供校验脚本 scripts/validate-openapi.mjs 做语法检查;
  5. 分三阶段流程:需求定义、规范设计、验证。

使用方法:按阶段参考对应文件——需求定义阶段查看 references/basics.md,规范设计阶段参考 agents/design-api.md 并基于模板编写,验证阶段参考 agents/validate-spec.md 并运行 scripts/validate-openapi.mjs。设计前应先确认端点数量、认证方式、速率限制,并判断是新建还是更新现有规范。

适用场景:新建或更新 OpenAPI 规范、设计端点与 Schema、排查 OpenAPI 语法错误、配置安全方案。

限制与注意:更新时需明确变更前后差异并检查是否破坏兼容性;安全方案应在设计阶段就纳入而非事后追加;避免跨端点 Schema 不一致、省略错误响应定义、required 字段含糊、硬编码安全配置;未经验证不要部署到生产环境。

其他:官方文本暂未提供;详细步骤请参考 references/ 目录;变更记录建议写入 CHANGELOG.md。