swagger-api / swagger-api/swagger-ui
Cannot reference YAML files, treated as JSONs
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
First steps
- Read the whole issue, then the project's contributing guide.
- Comment on the issue to say you are picking it up — it saves two people doing the same work.
- Fork the repository and make your change on a branch.
- 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