| name | metaframe-openapi-specification |
|---|---|
| category | api |
| description | OpenAPI规范 | API & Integration |
英文名: OpenAPI Specification
分类: API 设计与集成
作者: Tony Tam / Swagger (2011); donated to OpenAPI Initiative / Linux Foundation (2015)
复杂度: beginner
成熟度: established
AI 相关: ✅ 是
面向RESTful服务的机器可读API描述标准
- 设计优先方法：在实现API之前编写OpenAPI规范，将其作为前后端团队之间的契约
- 路径和操作对象：每个API端点由URL路径和HTTP方法定义，包含类型化的参数、请求体和响应模式
- 组件与复用：共享的模式、安全方案、参数和响应对象在components部分定义一次，通过$ref引用
- 代码生成：openapi-generator和swagger-codegen等工具从规范生成类型安全的客户端SDK、服务端存根和模拟服务器
- Lint与治理：规则集（如Spectral）在组织内所有API规范中强制执行命名约定、分页标准和错误格式
- 定义OpenAPI文档结构：以YAML或JSON格式描述info元数据、服务器URL和全局安全方案
- 将每个API端点描述为路径对象，包含HTTP方法、参数（路径、查询、头部）和请求体
- 在components部分使用JSON Schema定义可复用的请求/响应模型模式，减少重复
- 为每个状态码添加响应定义（包括错误响应），在适当处链接到组件模式
- 使用lint工具（Spectral、openapi-generator）验证规范，然后生成文档、客户端SDK和服务端存根
['当设计REST API需要文档、客户端生成和测试的单一事实来源时', '当多个团队消费你的API并需要明确的、机器可读的接口文档时', '当在组织中通过CI流水线的自动化lint来执行API设计标准时', '当构建开发者门户，交互式API探索（试用功能）对采用至关重要时']
- 采用设计优先的工作流，在编写任何代码之前编写并审查OpenAPI规范，因为这能在实现前发现API设计问题
- 广泛使用$ref进行模式复用，因为重复的模式不可避免地会漂移并导致不一致
- 将Spectral或类似的lint工具集成到CI中，因为它能自动执行组织的API标准
- 为所有请求和响应模式包含示例值，因为它们驱动交互式文档和模拟服务器
- 不要将从代码生成OpenAPI规范作为主要工作流，因为代码优先的方法产生的规范反映的是实现而非设计意图
- 不要忽略components部分并内联所有模式，因为这会导致大量重复和维护负担
- 不要仅将OpenAPI规范视为文档，因为其最大价值在于代码生成、测试和契约执行
- 不要跳过错误响应模式，因为未文档化的错误格式迫使消费者通过猜测来处理错误
Sources: SDFrame (Software Design) MetaFrame: 🔌 API & Integration / API 与集成