OAS 3 本指南适用于 OpenAPI 3.0。如果您使用 OpenAPI 2.0，请参阅我们的 OpenAPI 2.0 指南。

添加示例

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

注意 Swagger UI 用户：对多个 examples 的支持自 Swagger UI 3.23.0 和 Swagger 编辑器 3.6.31 起可用。

注意：不要将示例值与默认值混淆。示例说明了该值应该是怎样的。默认值是服务器在客户端没有提供该值时使用的值。

参数示例

这是一个参数值的示例

parameters:
  - in: query
    name: status
    schema:
      type: string
      enum: [approved, pending, closed, new]
      example: approved     # Example of a parameter value

参数的多个示例

parameters:
  - in: query
    name: limit
    schema:
      type: integer
      maximum: 50
    examples:       # Multiple examples
      zero:         # Distinct name
        value: 0    # Example value
        summary: A sample limit value  # Optional description
      max: # Distinct name
        value: 50   # Example value
        summary: A sample limit value  # Optional description

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

请求和响应体示例

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

paths:
  /users:
    post:
      summary: Adds a new user
      requestBody:
        content:
          application/json:
            schema:      # Request body contents
              type: object
              properties:
                id:
                  type: integer
                name:
                  type: string
              example:   # Sample object
                id: 10
                name: Jessica Smith
      responses:
        '200':
          description: OK

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

paths:
  /users:
    post:
      summary: Adds a new user
      requestBody:
        content:
          application/json:    # Media type
            schema:            # Request body contents
              $ref: '#/components/schemas/User'   # Reference to an object
            example:           # Child of media type because we use $ref above
              # Properties of a referenced object
              id: 10
              name: Jessica Smith
      responses:
        '200':
          description: OK

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

paths:
  /users:
    post:
      summary: Adds a new user
      requestBody:
        content:
          application/json:     # Media type
            schema:             # Request body contents
              $ref: '#/components/schemas/User'   # Reference to an object
            examples:    # Child of media type
              Jessica:   # Example 1
                value:
                  id: 10
                  name: Jessica Smith
              Ron:       # Example 2
                value:
                  id: 11
                  name: Ron Stewart
      responses:
        '200':
          description: OK

这是一个响应体中 example 的示例

responses:
  '200':
    description: A user object.
    content:
      application/json:
        schema:
          $ref: '#/components/schemas/User'   # Reference to an object
        example: 
          # Properties of the referenced object
          id: 10
          name: Jessica Smith

响应体中的多个示例

responses:
  '200':
    description: A user object.
    content:
      application/json:
        schema:
          $ref: '#/components/schemas/User'   # Reference to an object
        examples:
          Jessica:
            value:
              id: 10
              name: Jessica Smith
          Ron:
            value:
              id: 20
              name: Ron Stewart

注意：响应和请求体中的示例是自由格式的，但预期它们与主体模式兼容。

对象和属性示例

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

• 属性级示例

  components:
    schemas:
      User:    # Schema name
        type: object
        properties:
          id:
            type: integer
            format: int64
            example: 1          # Property example
          name:
            type: string
            example: New order  # Property example
  

• 对象级示例

  components:
    schemas:
      User:       # Schema name
        type: object
        properties:
          id:
            type: integer
          name:
            type: string
        example:   # Object-level example
          id: 1
          name: Jessica Smith
  

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

数组示例

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

components:
  schemas:
    ArrayOfInt:
      type: array
      items:
        type: integer
        format: int64
        example: 1

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

components:
  schemas:
    ArrayOfInt:
      type: array
      items:
        type: integer
        format: int64
      example: [1, 2, 3]

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

components:
  schemas:
    ArrayOfUsers:
      type: array
      items:
        type: object
        properties:
          id:
            type: integer
          name:
            type: string
      example:
        - id: 10
          name: Jessica Smith
        - id: 20
          name: Ron Stewart

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

XML 和 HTML 数据的示例

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

content:
  application/xml:
    schema:
      $ref: '#/components/schemas/xml'
    examples:
      xml:
        summary: A sample XML response
        value: '<objects><object><id>1</id><name>new</name></object><object><id>2</id></object></objects>'
  text/html:
    schema:
      type: string
    examples:
      html:
        summary: A list containing two items
        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 应指向包含字面示例内容（例如，对象、文件或图像）的资源

content:
  application/json:
    schema:
      $ref: '#/components/schemas/MyObject'
    examples:
      jsonObject:
        summary: A sample object
        externalValue: 'http://example.com/examples/object-example.json'
  application/pdf:
    schema:
      type: string
      format: binary
    examples:
      sampleFile:
        summary: A sample file
        externalValue: 'http://example.com/examples/example.pdf'

重复使用示例

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

content:
  application/json:
    schema:
      $ref: '#/components/schemas/MyObject'
    examples:
      objectExample:
        $ref: '#/components/examples/objectExample'
...
components:
  examples:
    objectExample:
      value:
        id: 1
        name: new object
      summary: A sample object

  

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