swagger-api / swagger-api/swagger-ui

nested relationship not displayed correctly

Open
#5,972 3 comments 2 reactions 0 assignees View on GitHub

Nobody has claimed this yet.

cat: specification specification: 3.x type: bug
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: Ubuntu
  • Browser: Chrome
  • Version: 81
  • Method of installation: https://editor.swagger.io
  • Swagger-Editor version: 3.8.0
  • Swagger/OpenAPI version: OpenAPI 3.0.2
Content & configuration

Example Swagger/OpenAPI definition:

openapi: "3.0.2"
info:
  version: "0.2"
  title: "test API"
components:
  schemas:
    User:
      allOf:
        - $ref: '#/components/schemas/BasicMixInModel'
        - $ref: '#/components/schemas/UserFullObject'
      type: object
    UserFullObject:
      allOf:
        - $ref: '#/components/schemas/UserBaseObject'
      type: object
      required:
        - id
      properties:
        id:
          type: string
    UserBaseObject:
      type: object
      properties:
        full_user_name:
          type: string
        email:
          type: string
        team_name:
          type: string
    BasicMixInModel:
      type: object
      properties:
        updated_by:
          type: string
        updated_at:
          type: string
          format: date-time
    UserList:
      type: object
      properties:
        query:
          type: string
        items:
          type: array
          items:
            $ref: "#/components/schemas/User"
paths:
  /users:
    get:
      description: "get all users. default sorted by id"
      responses:
        200:
          description: "successful operation"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/UserList"

Swagger-Editor configuration options:

none
Describe the bug you're encountering

in the preview for the users GET request, not all fields are displayed.

To reproduce...

paste the above swagger file into the editor and see the rendered result.

Expected behavior

all fields should be displayed which are defined in the swagger file.

Screenshots

this is the output with missing fields:

image

also the schema is not displaying those fields:

image

interestingly enough, in the Schemas section of the editor, everything gets resolved properly:

image

Additional context or thoughts

I searched if some similar bug is/was happening already, the closest i found were https://github.com/swagger-api/swagger-editor/issues/1892 and https://github.com/swagger-api/swagger-js/issues/1394 but for the first one, i'm not sure if its the same issue. and changing the order also does not help here in this case.

the problem arises, when a list/array has items of objects, which are composed by other objects (referenced with allOf), which in turn also already were built out of other objects.

why do i need this? the shown swagger file is actually the condensed version of our system, which contains a user permission model. we need those different levels of inheritance to properly document also POST and PATCH requests.

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 by pasting the provided OpenAPI definition into Swagger Editor and compare the rendered users GET preview and schema with the resolved Schemas section. Trace how nested array items and chained allOf references are rendered; done means all inherited fields appear in both the preview and schema displays.

Written by the indexing model from the issue text.

Assessment

Tech stack
javascript, openapi
Domain
documentation, frontend
Issue type
Bug
Difficulty
4/5
Estimated time
3-5 days
Activity status
Stale
Clarity
Clearly specified
Newbie friendliness
35/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.