Redocly / Redocly/redoc

oneOf type or array of same type generated examples

Open
#2,676 5 comments 0 reactions 0 assignees View on GitHub

Nobody has claimed this yet.

Type: Bug
Dominant language
TypeScript
Stars
25.9k
Forks
2.4k
Avg merge
13h 10m
Merged PRs (30d)
4

Description

Describe the bug
When having a schema as follows

MetaOrganisationMembership:
  oneOf:
  - $ref: '#/components/schemas/OrganisationMembership'
  - type: array
    items:
      $ref: '#/components/schemas/OrganisationMembership'

Redoc renders only one example, and the content is an empty array [ ].

The request body schema on the other hand correctly shows two options, with one of them being the type itself and the other being an array of the same type.

Only the example generation is the issue here.

Edit for clarification:

  • Redoc is only generating one example while it should generate two (this is due to the examples having the same key and overwriting each other).
  • The generated example is wrong (an empty array).

Expected behavior

There are two examples, one example of the type and other of the type in an array.

Minimal reproducible OpenAPI snippet(if possible)

If you give me an editor where I can edit the openapi.yaml and see the Redoc result I can create one.

Below is how the schema currently uses the MetaOrganisation schema.

post:
  operationId: organisations_members_create
  parameters:
  - in: path
    name: organisation_id
    schema:
      type: string
    required: true
  tags:
  - organisations-members
  requestBody:
    content:
      application/json:
        schema:
          $ref: '#/components/schemas/MetaOrganisationMembership'

Screenshots

This is correct:

Image

This is the generated example(s):

Image

This is how it looks like in swagger-ui:

Image

Swagger-ui only displays one of the examples. If the oneOf order is swapped then it renders this:

Image

Additional context

Redoc version: 2.4.0

After debugging this a bit, there are actually two issues here:

  1. The subSchema.title here has the same value ("OrganisationMembership") for both the type and the array of the same type, which means that only the last example in oneOf is kept. https://github.com/Redocly/redoc/blob/v2.4.0/src/services/models/MediaType.ts#L69
    • This means that swapping the oneOf order will also render one example in redoc:
      Image
    • The expected behvavior is two examples using a dropdown two switch between them.
  2. The Sampler returns [] as the sample for the array of type example. https://github.com/Redocly/redoc/blob/v2.4.0/src/services/models/MediaType.ts#L63

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

Read src/services/models/MediaType.ts at the referenced lines and trace how the Sampler produces oneOf examples. Verify the provided MetaOrganisationMembership schema: both variants should remain selectable despite sharing a title, and the array variant should contain an OrganisationMembership example rather than an empty array.

Written by the indexing model from the issue text.

Assessment

Tech stack
openapi, typescript
Domain
documentation
Issue type
Bug
Difficulty
3/5
Estimated time
1-2 days
Activity status
Stale
Clarity
Clearly specified
Newbie friendliness
38/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.