用途
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 生成和文档门户搭建。资料未提供该技能的具体安装命令、收费方式、支持平台或量化效果,这些信息暂未提供。