OpenAPI用于描述HTTP API标准格式

Posted on Views:

OpenAPI Specification（OAS）是一种用于描述 HTTP API 的标准格式。它让人和工具都能理解一个 API 的接口、参数、请求体、响应、认证方式等。核心价值：用一份机器可读的契约，统一 API 的设计、开发、测试和文档。

1. 当前版本

2. 一份OpenAPI文档描述什么

API 服务
├── 基本信息
├── 服务器地址
├── 接口路径与 HTTP 方法
│   ├── 请求参数
│   ├── 请求体
│   ├── 响应状态码
│   └── 响应数据结构
├── 数据模型
├── 认证与授权
└── 复用、扩展与其他配置

最核心的三个对象是：

  • Paths：有哪些接口，例如 GET /users。

  • Parameters / Request Body：接口接收什么。

  • Responses / Schemas：接口返回什么，以及数据结构是什么。

3. 最小示例

符合 OpenAPI 3.x 结构的YAML 示例：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
openapi: 3.1.0

info:
  title: User API
  version: 1.0.0

servers:
  - url: https://api.example.com

paths:
  /users/{id}:
    get:
      summary: 获取用户
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: integer
      responses:
        "200":
          description: 成功
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/User"
        "404":
          description: 用户不存在

components:
  schemas:
    User:
      type: object
      required:
        - id
        - name
      properties:
        id:
          type: integer
        name:
          type: string

这份文档表达的是：

调用 GET /users/{id}，必须提供整数类型的 id；成功返回一个 User 对象，找不到用户则返回 404。

OpenAPI 文档本身可以使用 YAML 或 JSON 表示；API 实际传输的数据不要求必须是 YAML 或 JSON。

4. 为什么要用openapi规范

一份规范可以被多种工具消费：

OpenAPI 文档
    ├── 生成 API 文档
    ├── 生成客户端 SDK
    ├── 生成服务端代码
    ├── 进行接口测试
    ├── 校验请求与响应
    └── 作为前后端协作契约