基本结构

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 可以是任意字符串。您可以使用主版本.次版本.修订版本（如语义版本控制），或任意格式，如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（生成）部分定义了 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）、HTTP 头（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

更多信息：描述参数。

响应

对于每个操作，您可以定义可能的 HTTP 状态码，例如 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 常见流程（隐式、密码、应用和授权码）

更多信息：认证。

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