提高 API 开发效率：详解 OpenAPI 接口规范最佳实践

OpenAPI 接口规范

OpenAPI 是描述 HTTP API 的标准方式。今天来讲讲它的接口规范（OpenAPI 规范 (中文版)）~

OpenAPI 版本号规范

OpenAPI 的版本号是使用 major.minor.patch 格式来定义的，比如 3.1.2

• major： 规定大版本

• minor： 规定小版本

• patch： 规定小版本中的修补

OpenAPI 格式规范

OpenAPI 可以使用 JSON 或 YAML 的格式，且字段区分大小写：

JSON 示例

YAML 示例

OpenAPI 文档结构规范

OpenAPI 文档可以是单个文档，也可以多个文档，由你们团队自行决定。在后一种情况， 需要在 Reference Objects 和 Schema Object 中使用 $ref 关键字。

而文档的命名，建议命名为 openapi.json 或 openapi.yaml。

OpenAPI 数据类型规范

OpenAPI 的数据类型，必须符合 JSON Schema Specification Draft 2020-12 的规范才行

JSON Schema 规范地址：https://datatracker.ietf.org/doc/html/draft-bhutton-json-schema-00#section-4.2.1

OpenAPI 富文本格式规范

OpenAPI 的 description 字段是支持 CommonMark markdown 格式的，所以在 OpenAPI 中使用富文本，格式必须符合 CommonMark markdown 格式。

OpenAPI 对象

Info Object

描述 API 的元数据

Contact Object

API 的联系信息

Server Object

API 的服务器对象信息

可以是一个服务器

也可以是多个服务器

Components Object

API 的可复用组件对象

Paths Object

描述 API 的 URL 的对象

Path Item Object

单个路径上可用操作的对象

Operation Object

路径上单个 API 操作的对象

External Documentation Object

拓展外部资源

Parameter Object

参数对象

Request Body Object

单个请求 Body 的对象

Responses Object

API 返回响应的对象

Header Object

请求头的对象

知识扩展：

• 理解 Swagger 和 OpenAPI：API 设计和文档化的最佳实践
  

• OpenAPI入门指南