Swagger Editor 3.8 examples not working for reference array schema

Question

This question is a follow-up to this similar one - as @Helen requested a new question be asked.

It seems an array type schema only accepts "example", not "examples". The following schema produces an error on the editor.swagger.io site:

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'

But if I replace the "examples" attribute with "example", e.g.:

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

then it works fine.

The referenced question is answered that "examples" is supported in Swagger Editor 3.6.21, and the comment by @Helen says that the editor.swagger.io site is using version 3.8.3.

Helen · Accepted Answer · 2020-05-29 16:44:23Z

4

Schemas do not support multiple examples, they only support a single example.

Multiple examples can only be used in:

request bodies: requestBody.content.<media-type>.examples
responses: responses.<code>.content.<media-type>.examples
parameters that use the content keyword: <parameter>.content.<media-type>.examples

answered May 29, 2020 at 16:44

Helen

99.8k18 gold badges280 silver badges352 bronze badges

Sign up to request clarification or add additional context in comments.

2 Comments

user9645 Over a year ago

Thanks. That is a big time bummer. Is there any way to $ref it? There are probably over 100 instances of that thing in our doc: get, post, patch(x2) for 30+ endpoints.

Helen Over a year ago

example doesn't support $ref. But in places where you can use multiple examples, you can $ref individual examples (swagger.io/docs/specification/adding-examples/#reuse).

Collectives™ on Stack Overflow

Swagger Editor 3.8 examples not working for reference array schema

1 Answer 1

2 Comments

Your Answer

Linked

Hot Network Questions

Collectives™ on Stack Overflow

1 Answer 1

2 Comments

Your Answer

Sign up or log in

Post as a guest

Linked

Related