swagger-api / swagger-ui

Swagger UI is a collection of HTML, JavaScript, and CSS assets that dynamically generate beautiful documentation from a Swagger-compliant API.
https://swagger.io
Apache License 2.0
26.59k stars 8.96k forks source link

nested relationship not displayed correctly #5972

Open drummerwolli opened 4 years ago

drummerwolli commented 4 years ago

Q&A (please complete the following information)

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.

waterkip commented 4 years ago

I have the same issue (I use swagger-ui and not the editor), and I agree that the allOf is where the problem is. If you remove it, it shows the missing fields of your referenced property member. You directly reference the object in your response (you can fiddle with the attached file) it will also show the object correctly.

Glitching the matrix

SomeType:
  type: object
  allOf:
    - Foo
  properties:
    some_ref:
      $ref: "#/components/schemas/Bar"   

Works fine

SomeType:
  type: object
  properties:
    some_ref:
      $ref: "#/components/schemas/Bar"   

I've checked that my specs validate with

docker pull jamescooke/openapi-validator
docker run --rm -v $(pwd)/openapi:/data jamescooke/openapi-validator zd.yml

And that works, I've also used another viewer and that one shows show the correct data.

In the schema view of the object I also get an incorrect schema view. I've added my reproduction path as well.

bug.txt

StenCalDabran commented 3 years ago

It actually is solvable by changing some order: if you make sure, that the paths property comes before the components property, everything works fine. Although different behavior, this may very well be based on the same root problem as swagger-api/swagger-js#1394.

jhmilan commented 2 years ago

It actually is solvable by changing some order: if you make sure, that the paths property comes before the components property, everything works fine. Although different behavior, this may very well be based on the same root problem as swagger-api/swagger-js#1394.

This is indeed a solution that fixes the issue. However, in some cases you can not change the spec because it is autogenerated (in my case https://docs.nestjs.com/openapi/introduction).

Any idea about what to do in those cases?