OpenAPI是什么？

OpenAPI被用来描述基于HTTP的API，是目前被广泛接受和使用的API工业标准。

使用OpenAPI规范的优势

  • 可以使用工具检查用户定义的API是否满足OpenAPI特定版本的规范，语法是否正确等。
  • 可以检查请求和响应中的数据是否正确。
  • 可以自动生成API文档。
  • 自动生成客户端和服务端的代码。
  • 可以用图形化工具快速、方便地创建API描述文件。
  • 可以在写代码之前创建提供示例响应的伪HTTP服务器。
  • 在API定义阶段就可以发现一些可能出现的安全漏洞。

API描述文件

API描述文件是一个机器可读的API定义文件。它应该是尽量完整的、细致的、明确的。开发者可以使用API描述文件来自动生成API文档以及代码。

格式: JSON 或者 YAML

最小化结构:

1
2
3
4
5
openapi: 3.1.0 # OpenAPI版本
info:
  title: A minimal OpenAPI document
  version: 0.0.1 # API版本
paths: {} # No endpoints defined

Servers对象

1
2
3
4
5
6
7
8
9
10
11
12
13
servers:
  - url: https://{username}.server.com:{port}/{version}
    variables:
      username:
        default: demo
        description: This value is assigned by the service provider.
      port:
        enum:
          - "8443"
          - "443"
        default: "8443"
      version:
        default: v1

路径对象:

1
2
3
4
5
6
paths:
  /board: # URI
    get: # HTTP方法
      ...
    put:
      ...

方法对象:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
get:
  summary: Get the whole board
  description: Retrieves the current state of the board and the winner.
  responses:
    "200":
      description: "OK"
      content:
        ...
post:
  summary: 
  description:
  response:
  requestBody:
  parameters:

response对象

1
2
3
4
5
6
7
8
9
paths:
  /board:
    get:
      responses:
        "200":
          description: Everything went fine.
          content:
            ...
        "404": ...

内容对象:

1
2
3
4
5
6
7
content:
  application/json:
    ...
  text/html:
    ...
  text/*:
    ...

Media类型对象:

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
content:
  application/json:
    schema:
      type: integer
      minimum: 1
      maximum: 100

content:
  application/json:
    schema:
      type: string
      enum:
      - Alice
      - Bob
      - Carl

content:
  application/json:
    schema:
      type: array
      minItems: 1
      maxItems: 10
      items:
        type: integer

content:
  application/json:
    schema:
      type: object
      properties:
        productName:
          type: string
        productPrice:
          type: number

requestBody对象

方法对象中的requestBody和parameters共同定义了HTTP请求中的数据。

1
2
3
4
5
6
7
requestBody:
  required: true
  content:
    application/json:
      schema:
        type: string
        enum: [".", "X", "O"]

parameters对象

1
2
3
4
5
6
7
8
9
10
11
paths:
  /users/{id}:
    get:
      parameters:
      - name: id  # 必须有的，定义参数名
        in: path  # 必须有的，定义参数的来源，可以是 path, query, header中的一个
        required: true # 可选的
        schema:
          type: integer
          minimum: 1
          maximum: 100

对象重用

可以使用components和ref来重用一个对象，例如：

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
components:
  schemas:
    coordinate:
      type: integer
      minimum: 1
      maximum: 3
  parameters:
    rowParam:
      name: row
      in: path
      required: true
      schema:
        $ref: "#/components/schemas/coordinate"
    columnParam:
      name: column
      in: path
      required: true
      schema:
        $ref: "#/components/schemas/coordinate"
paths:
  /board/{row}/{column}:
    post:
      parameters:
        - $ref: "#/components/parameters/rowParam"
        - $ref: "#/components/parameters/columnParam"
  /page/{row}/{column}:
    post:
      parameters:
        - $ref: "#/components/parameters/rowParam"
        - $ref: "#/components/parameters/columnParam"

文档格式

段落可以使用文本模式和折叠模式，文本模式中的段落会原样输出，而折叠模式将会自动换行。

1
2
3
4
5
6
7
8
9
10
11
文本模式输入：
description: |
  This is a string
  in multiple lines.

  And an extra one.
文本模式输出：
This is a string
in multiple lines.

And an extra one.
1
2
3
4
5
6
7
8
9
折叠模式输入：
description: >
  This is a string
  in multiple lines.

  And an extra one.
折叠模式输出：
This is a string in multiple lines.
And an extra one.

description对象中也支持markdown的语法

OpenAPI Generator

OpenAPI Generator可以根据OpenAPI的API描述文件自动生成客户端、服务器端代码以及API文档。使用homebrew安装的命令如下:

1
|$ brew install openapi-generator

生成代码的命令：

1
openapi-generator generate -i petstore.yaml -g ruby -o /tmp/test/

其中 -i指定API描述文件，-g指定代码语言，-o指定输出路径。

文档链接：https://openapi-generator.tech/docs/installation