Swagger Editor 3.8 示例不适用于参考数组架构答案

【问题标题】：Swagger Editor 3.8 examples not working for reference array schemaSwagger Editor 3.8 示例不适用于参考数组架构
【发布时间】：2020-05-29 15:00:30
【问题描述】：

这个问题是this similar one 的后续问题 - 因为@Helen 要求提出一个新问题。

似乎数组类型模式只接受“示例”，而不接受“示例”。以下架构在 editor.swagger.io 站点上产生错误：

info:
  title: Example Inc. REST API version 1.0
  version: '1.0'
openapi: 3.0.0
components:
  schemas:
    user_reference:
      properties:
        comment:
          type: string
        middle_name:
          type: string
        domain:
          pattern: '^[0-9A-Za-z][0-9A-Za-z.-]*$'
          type: string
        id:
          minimum: 1
          type: integer
        first_name:
          type: string
        last_name:
          type: string
        username:
          pattern: '^[0-9A-Za-z_.@-]+$'
          type: string
      type: object
    owners_reference_list:
      type: array
      items:
        $ref: '#/components/schemas/user_reference'
      examples:
        by_site:
          summary: Access by site and username
          value:
            - domain: example.com
              username: jsmith
        by_id:
          value:
            - id: 14
          summary: Access by id
        by_other:
          summary: Access by other attributes
          value:
            - middle_name: X.
              last_name: Smith
              comments: Standard user
              first_name: John
  responses:
    ok:
      content:
        application/json:
          schema:
            type: string
      description: |
        ...
paths:
  /users:
    description: |
      A user account ...
    get:
      parameters:
        - description: |
            ...
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/owners_reference_list'
          name: owners_ref
          required: false
          in: query
      responses:
        '200':
          $ref: '#/components/responses/ok'

但如果我将“examples”属性替换为“example”，例如：

owners_reference_list:
  type: array
  items:
    $ref: '#/components/schemas/user_reference'
  example:
        - domain: example.com
          username: jsmith

然后它就可以正常工作了。

回答引用的问题是 Swagger Editor 3.6.21 支持“示例”，@Helen 的评论说 editor.swagger.io 网站使用的是 3.8.3 版本。

【问题讨论】：

标签： swagger openapi swagger-editor

【解决方案1】：

架构不支持多个examples，它们只支持一个example。

多个examples只能用于：

请求正文：requestBody.content.<media-type>.examples
回复：responses.<code>.content.<media-type>.examples
使用content关键字的参数：<parameter>.content.<media-type>.examples

【讨论】：

谢谢。这是一个很大的麻烦。有没有办法$ref呢？在我们的文档中可能有超过 100 个实例：get、post、patch(x2) 用于 30 多个端点。
example 不支持$ref。但是在可以使用多个examples 的地方，您可以$ref 单个示例（swagger.io/docs/specification/adding-examples/#reuse）。