swagger-api / swagger-api/swagger-ui
Models sections are not rendered if YAML file uses externally $ref.
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: windows
- Browser: chrome
- Swagger-UI version: 3.22.1
Content & configuration
Example Swagger/OpenAPI definition:
openapi.yaml
openapi: 3.0.0
info:
title: Common Data Types
version: "1.0"
paths:
/{appId}/subscriptions:
get:
summary: read all of the active subscriptions for the applictaion.
operationId: getSubscriptionsById
parameters:
- name: appId
in: path
description: App ID
required: true
schema:
type: integer
format: int64
responses:
'200':
description: OK (Successful)
content:
application/json:
schema:
type: array
items:
$ref: 'schemas.yaml#/components/schemas/Category'
'400':
$ref: './responses.yaml#/components/responses/E400'
'401':
$ref: './responses.yaml#/components/responses/E401'
'500':
$ref: './responses.yaml#/components/responses/E500'
schemas.yaml
openapi: 3.0.0
info:
title: Common Data Types
version: "1.0"
paths: {}
components:
schemas:
Category:
type: "object"
properties:
id:
type: "integer"
format: "int64"
name:
type: "string"
xml:
name: "Category"
subscription:
type: string
responses.yaml
openapi: 3.0.0
info:
title: Common Data Types
version: "1.0"
paths: {}
components:
schemas:
ProblemDetails:
type: object
properties:
title:
type: string
description: A short, human-readable summary of the problem
status:
type: integer
description: The HTTP status code for this occurrence of the problem.
responses:
E400:
description: Bad request
E401:
description: Unauthorized
E500:
description: Server Error
content:
application/json:
schema:
$ref: '#/components/schemas/ProblemDetails'
Describe the bug you're encountering
I splitted my specs into multiple YAML file using $ref attribute.
Able to successfully generate stubs using command line java -jar openapi-generator-cli-4.0.0-beta3.jar generate -i openapi.yaml -g spring -o ./temp.
However, while rendering on Swagger UI, I see that Models are NOT displayed. And also schema names are not displayed correctly
what's wrong in referencing an external yaml file? If local references are used, UI is rendered correctly with Models section.
To reproduce...
- npm install -g http-server
- cd ...path_to_main_yaml_file/openapi
- http-server -p 3333 -c-1 --cors
- Open swagger ui (i.e. dist/index.html)
- updated
index.htmlwith urlhttp://localhost:3333/openapi.yaml - open the
index.html
Expected behavior
Should see the
Models
section on swagger UI And Schema name should be Category and Not schemas.yamlCategory
Screenshots

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 loading openapi.yaml through dist/index.html and compare the rendering of local and external $ref values in schemas.yaml and responses.yaml. The issue is done when Swagger UI displays the Models section and names the schema Category rather than schemas.yamlCategory.
Written by the indexing model from the issue text.
Assessment
- Tech stack
- javascript, openapi
- Domain
- frontend
- Issue type
- Bug
- Difficulty
- 3/5
- Estimated time
- 1-2 days
- Activity status
- Stale
- Clarity
- Mostly clear
- Newbie friendliness
- 38/100