Redocly / Redocly/redoc

OpenAPI 3.1 examples not rendered correctly

Open
#1,905 4 comments 5 reactions 1 assignee View on GitHub

@AlexVarchuk is already working on this.

Since May 5, 2022.

investigation need-design Type: Enhancement
Dominant language
TypeScript
Stars
25.9k
Forks
2.4k
Avg merge
13h 10m
Merged PRs (30d)
4

Description

Describe the bug
Having an array of examples in a schema definition, e.g. under #/components/schemas only renders the first one, not all of them.

Expected behavior
I expect to see all examples in the right pane.

Minimal reproducible OpenAPI snippet(if possible)

components:
  schemas:
    Test:
      type: object
      properties:
        id:
          type: integer
        title:
          type: string
      examples:
        - id: 123
          title: Test title
        - id: 456
          title: Another title

Screenshots

Bildschirmfoto 2022-02-14 um 09 18 45

Additional context
In openapi 3.1, example is deprecated. According to changes from openapi 3.0 to 3.1 (https://www.openapis.org/blog/2021/02/16/migrating-from-openapi-3-0-to-3-1-0) one should use examples instead of example and add several examples as a list.
It doesn't work either when adding multiple examples to the individual fields instead of the object, i.e.

components:
  schemas:
    Test:
      type: object
      properties:
        id:
          type: integer
        title:
          type: string
          examples:
            - Test title
            - Another title

also shows only the first one.

I expect to the all examples either directly listed or selectable (although openapi 3.1 examples are a list, not a hash with keys to select from). Since objects can become complex and properties may depend on each other, showing several real world examples with different use cases make sense.

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.

Assessment

This issue has not been assessed yet.

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.