SuperAPI AI 工具集

openapi-spec-generation

编程与开发

查看项目

更新于 10-16 07:30

技能介绍

用途

OpenAPI Spec Generation 是一套用于创建、维护和验证 RESTful API 的 OpenAPI 3.1 规范的模式集合。当需要编写 API 文档、从现有代码生成 OpenAPI 规范、设计 API 契约、验证 API 实现是否符合规范、从规范生成客户端 SDK,或搭建 API 文档门户时,可以使用该技能。

核心概念

OpenAPI 3.1 结构

规范的基本骨架包含以下顶层字段:

openapi: 3.1.0
info:
  title: API Title
  version: 1.0.0
servers:
  - url: https://api.example.com/v1
paths:
  /resources:
    get: ...
components:
  schemas: ...
  securitySchemes: ...

设计方法

该技能对比了三种设计取向:

  • 设计优先(Design-First):先写规范再写代码,适用于新 API 和契约场景。
  • 代码优先(Code-First):从代码生成规范,适用于已有 API。
  • 混合(Hybrid):在代码中加注解再生成规范,适用于持续演进的 API。

使用方式

资料给出了 OpenAPI 3.1 的结构示例与三种设计方法的对照表,并说明完整的模板库和详细示例位于 references/details.md,需要在具体模板时阅读该文件。

最佳实践

推荐做法:

  • 使用 $ref 复用 schema、参数和响应。
  • 添加示例,用真实取值帮助调用方理解。
  • 记录所有可能的错误码。
  • 对 API 做版本管理,可在 URL 或请求头中体现。
  • 规范变更使用语义化版本。

应避免的做法:

  • 不要使用笼统的描述,应保持具体。
  • 不要跳过安全定义,需定义所有安全方案。
  • 不要忘记 nullable,需对 null 明确标注。
  • 不要混用风格,命名应保持一致。
  • 不要硬编码 URL,应使用 server variables。

适用场景与限制

适用于 RESTful API 的文档编写、契约设计、规范验证、SDK 生成和文档门户搭建。资料未提供该技能的具体安装命令、收费方式、支持平台或量化效果,这些信息暂未提供。