添加示例

您可以向参数、属性和对象添加示例，使您的 Web 服务的 OpenAPI 规范更清晰。示例可以被以某种方式处理您的 API 的工具和库读取。例如，API 模拟工具可以使用示例值来生成模拟请求。您可以为对象、单个属性和操作参数指定示例。要指定示例，请使用 example 或 examples 键。请参阅下面的详细信息。

Swagger UI 用户须知：自 Swagger UI 3.23.0 和 Swagger Editor 3.6.31 起，支持多个 examples。

注意：不要将示例值与默认值混淆。示例说明值的预期值。默认值是客户端未提供值时服务器使用的值。

参数示例

这是参数值的示例

1
parameters:
2
  - in: query
3
    name: status
4
    schema:
5
      type: string
6
      enum: [approved, pending, closed, new]
7
      example: approved # Example of a parameter value

参数的多个示例

1
parameters:
2
  - in: query
3
    name: limit
4
    schema:
5
      type: integer
6
      maximum: 50
7
    examples: # Multiple examples
8
      zero: # Distinct name
9
        value: 0 # Example value
10
        summary: A sample limit value # Optional description
11
      max: # Distinct name
12
        value: 50 # Example value
13
        summary: A sample limit value # Optional description

如您所见，每个示例都有一个不同的键名。此外，在上面的代码中，我们使用了带有描述的可选 summary 键。注意：您指定的示例值应与参数数据类型匹配。

请求和响应体示例

这是请求体中 example 关键字的示例

1
paths:
2
  /users:
3
    post:
4
      summary: Adds a new user
5
      requestBody:
6
        content:
7
          application/json:
8
            schema: # Request body contents
9
              type: object
10
              properties:
11
                id:
12
                  type: integer
13
                name:
14
                  type: string
15
              example: # Sample object
16
                id: 10
17
                name: Jessica Smith
18
      responses:
19
        "200":
20
          description: OK

请注意，在上面的代码中，example 是 schema 的子项。如果 schema 引用 components 部分中定义的某个对象，那么您应该使 example 成为媒体类型关键字的子项

1
paths:
2
  /users:
3
    post:
4
      summary: Adds a new user
5
      requestBody:
6
        content:
7
          application/json: # Media type
8
            schema: # Request body contents
9
              $ref: "#/components/schemas/User" # Reference to an object
10
            example: # Child of media type because we use $ref above
11
              # Properties of a referenced object
12
              id: 10
13
              name: Jessica Smith
14
      responses:
15
        "200":
16
          description: OK

这是因为 $ref 会覆盖其旁边的所有兄弟项。如果需要，您可以使用多个示例

1
paths:
2
  /users:
3
    post:
4
      summary: Adds a new user
5
      requestBody:
6
        content:
7
          application/json: # Media type
8
            schema: # Request body contents
9
              $ref: "#/components/schemas/User" # Reference to an object
10
            examples: # Child of media type
11
              Jessica: # Example 1
12
                value:
13
                  id: 10
14
                  name: Jessica Smith
15
              Ron: # Example 2
16
                value:
17
                  id: 11
18
                  name: Ron Stewart
19
      responses:
20
        "200":
21
          description: OK

这是响应体中 example 的示例

1
responses:
2
  "200":
3
    description: A user object.
4
    content:
5
      application/json:
6
        schema:
7
          $ref: "#/components/schemas/User" # Reference to an object
8
        example:
9
          # Properties of the referenced object
10
          id: 10
11
          name: Jessica Smith

响应体中的多个示例

1
responses:
2
  "200":
3
    description: A user object.
4
    content:
5
      application/json:
6
        schema:
7
          $ref: "#/components/schemas/User" # Reference to an object
8
        examples:
9
          Jessica:
10
            value:
11
              id: 10
12
              name: Jessica Smith
13
          Ron:
14
            value:
15
              id: 20
16
              name: Ron Stewart

注意：响应和请求体中的示例是自由格式的，但应与主体架构兼容。

对象和属性示例

您还可以在 components 部分中为对象和单个属性指定示例。

属性级示例

1
components:
2
  schemas:
3
    User: # Schema name
4
      type: object
5
      properties:
6
        id:
7
          type: integer
8
          format: int64
9
          example: 1 # Property example
10
        name:
11
          type: string
12
          example: New order # Property example

对象级示例

1
components:
2
  schemas:
3
    User: # Schema name
4
      type: object
5
      properties:
6
        id:
7
          type: integer
8
        name:
9
          type: string
10
      example: # Object-level example
11
        id: 1
12
        name: Jessica Smith

请注意，架构和属性支持单个 example，但不支持多个 examples。

数组示例

您可以添加单个数组项的示例

1
components:
2
  schemas:
3
    ArrayOfInt:
4
      type: array
5
      items:
6
        type: integer
7
        format: int64
8
        example: 1

或包含多个项的数组级示例

1
components:
2
  schemas:
3
    ArrayOfInt:
4
      type: array
5
      items:
6
        type: integer
7
        format: int64
8
      example: [1, 2, 3]

如果数组包含对象，您可以按如下方式指定多项示例

1
components:
2
  schemas:
3
    ArrayOfUsers:
4
      type: array
5
      items:
6
        type: object
7
        properties:
8
          id:
9
            type: integer
10
          name:
11
            type: string
12
      example:
13
        - id: 10
14
          name: Jessica Smith
15
        - id: 20
16
          name: Ron Stewart

请注意，数组和数组项支持单个 example，但不支持多个 examples。

XML 和 HTML 数据示例

要描述无法以 JSON 或 YAML 格式表示的示例值，请将其指定为字符串

1
content:
2
  application/xml:
3
    schema:
4
      $ref: "#/components/schemas/xml"
5
    examples:
6
      xml:
7
        summary: A sample XML response
8
        value: "<objects><object><id>1</id><name>new</name></object><object><id>2</id></object></objects>"
9
  text/html:
10
    schema:
11
      type: string
12
    examples:
13
      html:
14
        summary: A list containing two items
15
        value: "<html><body><ul><li>item 1</li><li>item 2</li></ul></body></html>"

您可以在此 Stack Overflow 帖子中找到有关在 YAML 中编写多行字符串的信息：https://stackoverflow.com/questions/3790454/in-yaml-how-do-i-break-a-string-over-multiple-lines。

外部示例

如果由于某种原因无法将示例值插入到您的规范中，例如，它既不符合 YAML 也不符合 JSON，您可以使用 externalValue 关键字来指定示例值的 URL。该 URL 应指向包含字面示例内容（例如，对象、文件或图像）的资源

1
content:
2
  application/json:
3
    schema:
4
      $ref: "#/components/schemas/MyObject"
5
    examples:
6
      jsonObject:
7
        summary: A sample object
8
        externalValue: "http://example.com/examples/object-example.json"
9
  application/pdf:
10
    schema:
11
      type: string
12
      format: binary
13
    examples:
14
      sampleFile:
15
        summary: A sample file
16
        externalValue: "http://example.com/examples/example.pdf"

重用示例

您可以在规范的 components/examples 部分中定义常用示例，然后在各种参数描述、请求和响应体描述、对象和属性中重复使用它们

1
    content:
2
      application/json:
3
        schema:
4
          $ref: '#/components/schemas/MyObject'
5
        examples:
6
          objectExample:
7
            $ref: '#/components/examples/objectExample'
8
    ...
9
    components:
10
      examples:
11
        objectExample:
12
          value:
13
            id: 1
14
            name: new object
15
          summary: A sample object

没有找到您要找的内容？咨询社区
发现错误？请告知我们