swagger-api / swagger-api/swagger-ui

$ref not being rendered in response example

Open
#8,308 2 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

Q&A (please complete the following information)
  • OS: Manjaro
  • Browser: Chrome
  • Version: 107
  • Method of installation: docker
  • Swagger-UI version: v4.13.2
  • Swagger/OpenAPI version: OpenAPI 3.0
Content & configuration

The swagger content and configuration is split among multiple files, see repository github.com/ygurin/swagger-bug-demo.

The structure of the project looks like so:

.
├── Dockerfile
├── openapi
│   ├── components
│   │   ├── examples
│   │   │   └── foo
│   │   │       └── getFooResponse.json
│   │   ├── headers
│   │   │   ├── channel.yaml
│   │   │   └── key.yaml
│   │   └── schemas
│   │       └── foo
│   │           └── get-foo-response-schema.json
│   ├── openapi.yaml
│   └── paths
│       └── foo
│           └── foo.yaml
└── README.md

9 directories, 8 files

This is the main openapi.yaml file:

openapi: 3.0.0
info:
  version: '1'
  title: ''
  description: 'Demo of a bug in swagger'
paths:
  /api/foo:
    $ref: 'paths/foo/foo.yaml'

points to paths/foo/foo.yaml

get:
      tags:
        - foo
      summary: Get a list of foo
      description: |
        Get a list of Foo
      operationId: account
      parameters:
        - $ref: ../../components/headers/key.yaml
        - $ref: ../../components/headers/channel.yaml
      responses:
        "200":
          description: OK
          content:
            application/json:
              schema:
                $ref: "../../components/schemas/foo/get-foo-response-schema.json"
              examples:
                response:
                  value:
                    $ref: "../../components/examples/foo/getFooResponse.json"
        "404":
          description: Not found
        "410":
          description: error
Describe the bug you're encountering

The $ref described in the example: does not render. Instead, it displays the $ref string.

To reproduce...

Steps to reproduce the behaviour:

  1. Download the repository found here
  2. Build the docker container docker build -t foo:v1 .
  3. Run the docker container docker run --rm -p 80:8080 -e API_URL="openapi/openapi.yaml" foo:v1
  4. Access http://localhost/
Expected behavior

Swagger UI renders the referenced example in the response.

Screenshots

Screenshot from 2022-11-25 19-05-40

Additional context or thoughts

I'm currently using an extension in VScode called OpenAPI (Swagger) Editor. This uses a version of Swagger-UI.

It seems to render the example with no issues, see the screenshot below:
Screenshot from 2022-11-25 19-09-27

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

Reproduce the issue with the linked swagger-bug-demo repository using its Dockerfile and openapi/openapi.yaml, then trace Swagger UI's response example rendering for the referenced value in paths/foo/foo.yaml. Done means the referenced getFooResponse.json content is rendered as the response example instead of the $ref string.

Written by the indexing model from the issue text.

Assessment

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

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.