Skip to content

Examples added in OpenAPI Spec 3.1 are not being displayed. #1158

Open
@dsuket

Description

@dsuket

Describe the bug

In OpenAPI Spec 3.1, examples were added to some objects for compatibility with JSON Schema.
https://swagger.io/specification/#example-object

However, this plugin doesn’t fully support that.
Specifically, the following request/response types are not supported.

  1. Request
    1.1. Request Parameter: OK
    1.2. Media Type Object: NO
    1.3. Schema Object: NO
    1.4. Schema Property Object: NO
  2. Response
    2.1. Media Type Object: OK
    2.2. Schema Object: NO
    2.3. Schema Property Object: NO

Expected behavior

The examples must be displayed correctly.

In particular, since example is deprecated in Schema Object and Schema Property Object, it’s important to support examples instead.
https://swagger.io/specification/#schema-object

Current behavior

I verified it using an examples test in the demo's test suite.

1.1. Request Parameter: OK
Image

1.2. Media Type Object in Request Body: NO
Image

1.3. Schema Object in Request Body: NO
Image

1.4. Schema Property Object in Request Body: NO
Image

2.1. Media Type Object: OK
Image

2.2. Schema Object in Response Body: NO
Image

2.3. Schema Property Object in Response Body: NO
Image

Possible solution

For Response, the Media Type Object is already displayed correctly, so it should be shown in the same way.

For Request, however, the request body doesn’t have Schema and Example tabs like the response does. First, we should add Schema and Example tabs to the request body.
Then, we can support examples just like in the response.

What do you think? If you're okay with it, I’ll go ahead and create a few PRs.

Steps to reproduce

  1. Add the examples test cases for tests in the demo.
  2. Build and start the server to check it.

examples test cases:

examples.yaml
openapi: 3.1.0
info:
  title: Examples Demo API
  description: Demonstrates various examples schema combinations.
  version: 1.0.0
  license:
    name: MIT
    url: https://opensource.org/licenses/MIT
security: []
servers:
  - url: http://test.local:8080
    description: Local server
tags:
  - name: examples
    description: examples
paths:
  /requestParameters/example:
    get:
      tags:
        - examples
      summary: example in request parameters
      parameters:
        - name: name
          description: name example
          in: query
          schema:
            type: string
          example: "John Doe"
        - name: age
          description: age example
          in: query
          schema:
            type: number
          example: 25
      responses:
        "204":
          description: no content

  /requestParameters/examples:
    get:
      tags:
        - examples
      summary: examples in request parameters
      parameters:
        - name: name
          description: name example
          in: query
          schema:
            type: string
          examples:
            example1:
              summary: "name example 1"
              description: "name example 1 description"
              value: "John Doe"
            example2:
              summary: "name example 2"
              description: "name example 2 description"
              value: "Jane Doe"
      responses:
        "204":
          description: no content

  /requestParameters/schema/example:
    get:
      tags:
        - examples
      summary: example in request parameters schema
      parameters:
        - name: name
          description: name example
          in: query
          schema:
            type: string
            example: "John Doe"
        - name: age
          description: age example
          in: query
          schema:
            type: number
            example: 25
      responses:
        "204":
          description: no content

  /requestParameters/schema/examples:
    get:
      tags:
        - examples
      summary: examples in request parameters schema
      parameters:
        - name: name
          description: name example
          in: query
          schema:
            type: string
            examples:
              - "John Doe"
              - "Jane Smith"
        - name: age
          description: age example
          in: query
          schema:
            type: number
            examples:
              - 25
              - 30
      responses:
        "204":
          description: no content

  /requestBody/mediaTypeObject/example:
    post:
      tags:
        - examples
      summary: example of media type object in requestBody
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                name:
                  type: string
                age:
                  type: number
                isStudent:
                  type: boolean
            example:
              name: "John Doe"
              age: 25
              isStudent: false
      responses:
        "204":
          description: no content

  /requestBody/mediaTypeObject/examples:
    post:
      tags:
        - examples
      summary: examples of media type object in requestBody
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                name:
                  type: string
                age:
                  type: number
                isStudent:
                  type: boolean
            examples:
              example1:
                value:
                  name: "John Doe"
                  age: 25
                  isStudent: false
              example2:
                value:
                  name: "Jane Smith"
                  age: 30
                  isStudent: true
      responses:
        "204":
          description: no content

  /requestBody/schema/example:
    post:
      tags:
        - examples
      summary: example of schema in requestBody
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                name:
                  type: string
                age:
                  type: number
                isStudent:
                  type: boolean
              example:
                name: "John Doe"
                age: 25
                isStudent: false
      responses:
        "204":
          description: no content

  /requestBody/schema/examples:
    post:
      tags:
        - examples
      summary: examples of schema in requestBody
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                name:
                  type: string
                age:
                  type: number
                isStudent:
                  type: boolean
              examples:
                - name: "John Doe"
                  age: 25
                  isStudent: false
                - name: "Jane Smith"
                  age: 30
                  isStudent: true
      responses:
        "204":
          description: no content

  /requestBody/schema/properties/example:
    post:
      tags:
        - examples
      summary: example of properties in requestBody schema
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                name:
                  type: string
                  example: "John Doe"
                age:
                  type: number
                  example: 25
                isStudent:
                  type: boolean
                  example: false
      responses:
        "204":
          description: no content

  /requestBody/schema/properties/examples:
    post:
      tags:
        - examples
      summary: examples of properties in requestBody schema
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                name:
                  type: string
                  examples:
                    - "John Doe"
                    - "Jane Smith"
                age:
                  type: number
                  examples:
                    - 25
                    - 30
                isStudent:
                  type: boolean
                  examples:
                    - true
                    - false
      responses:
        "204":
          description: no content

  /response/mediaTypeObject/example:
    get:
      tags:
        - examples
      summary: example of media type object in response
      responses:
        "200":
          description: successful response
          content:
            application/json:
              schema:
                type: object
                properties:
                  name:
                    type: string
                  age:
                    type: number
                  isStudent:
                    type: boolean
              example:
                name: "John Doe"
                age: 25
                isStudent: false

  /response/mediaTypeObject/examples:
    get:
      tags:
        - examples
      summary: examples of media type object in response
      responses:
        "200":
          description: successful response
          content:
            application/json:
              schema:
                type: object
                properties:
                  name:
                    type: string
                  age:
                    type: number
                  isStudent:
                    type: boolean
              examples:
                example1:
                  value:
                    name: "John Doe"
                    age: 25
                    isStudent: false
                example2:
                  value:
                    name: "Jane Smith"
                    age: 30
                    isStudent: true

  /response/schema/example:
    get:
      tags:
        - examples
      summary: example of schema in response
      responses:
        "200":
          description: successful response
          content:
            application/json:
              schema:
                type: object
                properties:
                  name:
                    type: string
                  age:
                    type: number
                  isStudent:
                    type: boolean
                example:
                  name: "John Doe"
                  age: 25
                  isStudent: false

  /response/schema/examples:
    get:
      tags:
        - examples
      summary: examples of schema in response
      responses:
        "200":
          description: successful response
          content:
            application/json:
              schema:
                type: object
                properties:
                  name:
                    type: string
                  age:
                    type: number
                  isStudent:
                    type: boolean
                examples:
                  - name: "John Doe"
                    age: 25
                    isStudent: false
                  - name: "Jane Smith"
                    age: 30
                    isStudent: true

  /response/schema/properties/example:
    get:
      tags:
        - examples
      summary: example of schema properties in response
      responses:
        "200":
          description: successful response
          content:
            application/json:
              schema:
                type: object
                properties:
                  name:
                    type: string
                    example: "John Doe"
                  age:
                    type: number
                    example: 25
                  isStudent:
                    type: boolean
                    example: false

  /response/schema/properties/examples:
    get:
      tags:
        - examples
      summary: examples of schema properties in response
      responses:
        "200":
          description: successful response
          content:
            application/json:
              schema:
                type: object
                properties:
                  name:
                    type: string
                    examples:
                      - "John Doe"
                      - "Jane Smith"
                  age:
                    type: number
                    examples:
                      - 25
                      - 30
                  isStudent:
                    type: boolean
                    examples:
                      - true
                      - false

Screenshots

Context

Your Environment

  • Version used:
  • Environment name and version (e.g. Chrome 59, node.js 5.4, python 3.7.3):
  • Operating System and version (desktop or mobile):
  • Link to your project:

Metadata

Metadata

Assignees

No one assigned

    Labels

    bugSomething isn't working

    Type

    No type

    Projects

    No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions