基本结构

Swagger 定义可以使用 JSON 或 YAML 编写。在本指南中，我们仅使用 YAML 示例，但 JSON 同样适用。使用 YAML 编写的 Swagger 规范示例如下

1
swagger: "2.0"
2
info:
3
  title: Sample API
4
  description: API description in Markdown.
5
  version: 1.0.0
6

7
host: api.example.com
8
basePath: /v1
9
schemes:
10
  - https
11

12
paths:
13
  /users:
14
    get:
15
      summary: Returns a list of users.
16
      description: Optional extended description in Markdown.
17
      produces:
18
        - application/json
19
      responses:
20
        200:
21
          description: OK

元数据

每个 Swagger 规范都以 Swagger 版本开始，2.0 是最新版本。Swagger 版本定义了 API 规范的总体结构——您可以记录什么以及如何记录它。

1
swagger: "2.0"

然后，您需要指定 API 的 info - title、description (可选)、version (API 版本，而不是文件修订版或 Swagger 版本)。

1
info:
2
  title: Sample API
3
  description: API description in Markdown.
4
  version: 1.0.0

version 可以是任意字符串。您可以使用major.minor.patch (如语义版本控制中所示)，或者任意格式，例如 1.0-beta 或 2016.11.15。description 可以是多行，并且支持 GitHub Flavored Markdown 以进行富文本表示。info 还支持其他字段，用于联系信息、许可证和其他详细信息。参考： 信息对象。

基本 URL

所有 API 调用的基本 URL 使用 schemes、host 和 basePath 定义

1
host: api.example.com
2
basePath: /v1
3
schemes:
4
  - https

所有 API 路径都相对于基本 URL。例如，/users 实际上表示 https://api.example.com/v1/users。更多信息： API 主机和基本 URL。

Consumes, Produces

consumes 和 produces 部分定义 API 支持的 MIME 类型。根级别的定义可以在各个操作中被覆盖。

1
consumes:
2
  - application/json
3
  - application/xml
4
produces:
5
  - application/json
6
  - application/xml

更多信息： MIME 类型。

路径

paths 部分定义 API 中的各个端点（路径）以及这些端点支持的 HTTP 方法（操作）。例如，GET /users 可以描述为

1
paths:
2
  /users:
3
    get:
4
      summary: Returns a list of users.
5
      description: Optional extended description in Markdown.
6
      produces:
7
        - application/json
8
      responses:
9
        200:
10
          description: OK

更多信息： 路径和操作。

参数

操作可以具有通过 URL 路径 (/users/{userId})、查询字符串 (/users?role=admin)、标头 (X-CustomHeader: Value) 和请求正文传递的参数。您可以定义参数类型、格式、它们是必需的还是可选的以及其他详细信息

1
paths:
2
  /users/{userId}:
3
    get:
4
      summary: Returns a user by ID.
5
      parameters:
6
        - in: path
7
          name: userId
8
          required: true
9
          type: integer
10
          minimum: 1
11
          description: Parameter description in Markdown.
12
      responses:
13
        200:
14
          description: OK

更多信息： 描述参数。

响应

对于每个操作，您可以定义可能的状态代码，例如 200 OK 或 404 Not Found，以及响应正文的 schema。架构可以在内联定义，也可以通过 $ref 从外部定义引用。您还可以为不同的内容类型提供示例响应。

1
paths:
2
  /users/{userId}:
3
    get:
4
      summary: Returns a user by ID.
5
      parameters:
6
        - in: path
7
          name: userId
8
          required: true
9
          type: integer
10
          minimum: 1
11
          description: The ID of the user to return.
12
      responses:
13
        200:
14
          description: A User object.
15
          schema:
16
            type: object
17
            properties:
18
              id:
19
                type: integer
20
                example: 4
21
              name:
22
                type: string
23
                example: Arthur Dent
24
        400:
25
          description: The specified user ID is invalid (e.g. not a number).
26
        404:
27
          description: A user with the specified ID was not found.
28
        default:
29
          description: Unexpected error

更多信息： 描述响应。

输入和输出模型

全局 definitions 部分允许您定义 API 中使用的通用数据结构。只要需要 schema，就可以通过 $ref 引用它们 - 用于请求正文和响应正文。例如，此 JSON 对象

1
{
2
  "id": 4,
3
  "name": "Arthur Dent"
4
}

可以表示为

1
definitions:
2
  User:
3
    properties:
4
      id:
5
        type: integer
6
      name:
7
        type: string
8
    # Both properties are required
9
    required:
10
      - id
11
      - name

然后，在请求正文架构和响应正文架构中引用如下

1
paths:
2
  /users/{userId}:
3
    get:
4
      summary: Returns a user by ID.
5
      parameters:
6
        - in: path
7
          name: userId
8
          required: true
9
          type: integer
10
      responses:
11
        200:
12
          description: OK
13
          schema:
14
            $ref: "#/definitions/User"
15
  /users:
16
    post:
17
      summary: Creates a new user.
18
      parameters:
19
        - in: body
20
          name: user
21
          schema:
22
            $ref: "#/definitions/User"
23
      responses:
24
        200:
25
          description: OK

身份验证

securityDefinitions 和 security 关键字用于描述 API 中使用的身份验证方法。

1
securityDefinitions:
2
  BasicAuth:
3
    type: basic
4

5
security:
6
  - BasicAuth: []

支持的身份验证方法有

基本身份验证
API 密钥 (作为标头或查询参数)
OAuth 2 通用流程（隐式、密码、应用程序和访问代码）

更多信息： 身份验证。

没有找到您要找的内容？向社区提问
发现错误？请告诉我们