swagger-api / swagger-api/swagger-ui

Cannot reference YAML files, treated as JSONs

Open
#5,325 3 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

Environment:

  • MacOSX
  • Chrome, Firefox
  • swagger-ui version: 3.22.1
  • installation: dist
  • OAS version: 3.0.2

Problem description:

I have a simple openapi file, which references other files using $ref. Both the main spec and the included files are in YAML format. However, it looks like the browser expects the included files to be formatted as JSONs only.

Main file:

openapi: 3.0.2
info:
  title: tile
  description: description
paths:
  /services:
    get:
      summary: summary
      description: description
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: schemas/payload.yaml

Included file, schemas/payload.yaml:

type: object
properties:
  property:
    type: string
    description: description

When the main file is explored, swagger UI displays an error "Could not render this component, see the console", and JavaScript console shows the following warning:

TypeError: Cannot read property 'toJS' of undefined
    at t.value (response.jsx:104)
    at t.render (root-injects.jsx:93)
    at s._renderValidatedComponentWithoutOwnerOrContext (ReactCompositeComponent.js:796)
    at s._renderValidatedComponent (ReactCompositeComponent.js:819)
    at s.performInitialMount (ReactCompositeComponent.js:359)
    at s.mountComponent (ReactCompositeComponent.js:255)
    at Object.mountComponent (ReactReconciler.js:43)
    at X.mountChildren (ReactMultiChild.js:234)
    at X._createInitialChildren (ReactDOMComponent.js:701)
    at X.mountComponent (ReactDOMComponent.js:520)

This is not specific to responses, same issue observed, for example, if I try to $ref a path. Note, however, if I change the referenced file from YAML to JSON, adding curled brackets, commas, and quotes, it's handled by swagger UI correctly.

All files are served from the same server, Content-Type is application/json. If I change my server code to return application/yaml (which hasn't been accepted as a standard mime type yet, but still), UI is broken with 406 errors, as it sends "Accept: application/json" only.

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 referenced YAML case in the dist installation and inspect the response.jsx stack-trace location in the browser console. Done means Swagger UI renders responses and paths that use YAML $ref files, including when the server serves them with an appropriate YAML content type.

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.