swagger-api / swagger-api/swagger-ui

Models sections are not rendered if YAML file uses externally $ref.

Open
#5,318 7 comments 5 reactions 0 assignees View on GitHub

Nobody has claimed this yet.

cat: rendering cat: style & presentation
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.html with url http://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

image

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 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

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.