swagger-api / swagger-api/swagger-ui

OpenAPI 3.0: references defined in examples should not be dereferenced

Open
#10,328 0 comments 0 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

When defining a reference inside of examples fields on various spec objects, instead of the Example Object, the reference should not be dereferenced.

For this specification:

  responses:
    ExampleResponse:
      description: An error occurred
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ExampleModel'
          examples:
            $ref: '#/components/examples/tshirt'
  examples:
    tshirt:
      summary: Sample T-shirt data
      value:
        # Example value starts here
        id: 17
        name: T-shirt
        description: 100% cotton shirt
        categories: [clothes]

when the example gets dereferenced, each field of tshirt will be seen as a separate example. Each of them will be rendered as an option for examples select:

Screenshot 2024-07-15 at 09 32 07

This does not happen for OpenAPI 3.1:

Screenshot 2024-07-15 at 12 43 53
Additional context or thoughts

To fix this, we need to utilise ApiDOM for OpenAPI 3.0.


Originally reported by @glowcloud

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 by reproducing the issue with the OpenAPI 3.0 YAML example in this report and compare it with the OpenAPI 3.1 behavior. Trace the OpenAPI 3.0 dereferencing path and investigate how ApiDOM can preserve the reference as one Example Object. Done means the referenced example renders as a single selectable example rather than separate fields.

Written by the indexing model from the issue text.

Assessment

Tech stack
javascript, openapi
Domain
api
Issue type
Bug
Difficulty
4/5
Estimated time
3-5 days
Activity status
Stale
Clarity
Mostly clear
Newbie friendliness
45/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.