OpenAPI接口规范：构建高效API服务的核心指南！

迈不过友情╰ 2024-03-17 14:52 17阅读 0赞

### **OpenAPI 接口规范** ###

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

![b1e17c035dd42a290e3f08af2fc3cf32.png][]

#### **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 规范地址：[draft-bhutton-json-schema-00][]

#### **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 设计和文档化的最佳实践][Swagger _ OpenAPI_API]**
 *  **[OpenAPI入门指南][OpenAPI 1]**

[OpenAPI _]: https://openapi.xiniushu.com/
[b1e17c035dd42a290e3f08af2fc3cf32.png]: https://image.dandelioncloud.cn/pgy_files/images/2024/03/15/e747b16a31d243059eea02c38f843099.png
[JSON]: https://apifox.com/apiskills/what-is-json/
[OpenAPI]: https://apifox.com/apiskills/what-is-openapi/
[draft-bhutton-json-schema-00]: https://datatracker.ietf.org/doc/html/draft-bhutton-json-schema-00#section-4.2.1
[API]: https://apifox.com/apiskills/understanding-apis/
[Swagger _ OpenAPI_API]: https://apifox.com/apiskills/swagger-and-openapi/
[OpenAPI 1]: https://apifox.com/apiskills/openapi-tutorials/