swagger-api / swagger-api/swagger-ui

OpenAPI 3.1.0 support: Open API 3.1.0: `examples` from `schema` of parameters not shown in Swagger UI

Open
#9,045 1 comment 15 reactions 0 assignees View on GitHub

Nobody has claimed this yet.

Dominant language
JavaScript
Stars
29k
Forks
9.3k
Avg merge
2d 23h
Merged PRs (30d)
25

Description

The list of examples from schema of parameters is not shown in Swagger UI:

Example: OpenApi: 3.1.0, SwaggerUI 5.1.3

openapi: 3.1.0
info:
  title: Test-API
  version: 1.0.0
paths:
  /api/v1/example/{name}/{version}/:
    get:
      parameters:
        - name: name
          required: true
          in: path
          description: Parameter with string as example
          schema:
            title: Name
            type: string
            examples:
              - Test Name
        - name: version
          required: true
          in: path
          description: Parameter with list as example
          schema:
            title: Version
            type: string
            examples:
              - value: stable
                summary: Stable version
              - value: latest
                summary: Latest version
      responses:
        '200':
          description: Successful Response

In the rendered SwaggerUI no examples are shown:

image

Example: OpenApi: 3.0.2, SwaggerUI 5.1.3

With version 3.0.2 of OpenApi the examples are shown correctly in the Swagger UI:

openapi: 3.0.2
info:
  title: Test-API
  version: 1.0.0
paths:
  /api/v1/example/{name}/{version}/:
    get:
      parameters:
        - name: name
          required: true
          in: path
          description: Parameter with string as example
          schema:
            title: Name
            type: string
          example: Test Name
        - name: version
          required: true
          in: path
          description: Parameter with list as example
          schema:
            title: Version
            type: string
          examples:
            Stable:
              summary: Stable version
              value: stable
            Latest:
              summary: Latest version
              value: latest
      responses:
        '200':
          description: Successful Response

image

Is this a bug in the current version of the Swagger UI or will the examples of the Schema not displayed in the UI?

Contributor guide

Open the contributing guide

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. Open a pull request that references the issue number.

Research direction

Start with the supplied OpenAPI 3.1.0 parameter example in Swagger UI 5.1.3 and compare its rendering with the OpenAPI 3.0.2 example. Trace how parameter schema examples are displayed; done means both the single string example and the list of value/summary examples appear in the rendered UI.

Written by the indexing model from the issue text.

Assessment

Tech stack
javascript, openapi
Domain
documentation, frontend
Issue type
Bug
Difficulty
3/5
Estimated time
1-2 days
Activity status
Stale
Clarity
Mostly clear
Newbie friendliness
42/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.