Swagger: openapi does not display nullable schemas

[zaunermax]

Bug Report

Current behavior

When using the openapi feature i noticed, that some of my nested DTOs are not correctly shown when it is nullable:

when removing nullable: true - the DTO is displayed correctly.

Input Code

@ApiProperty({ type: LogisticsPartnerDTO, nullable: true })
customer!: Nullable<LogisticsPartnerWithLocationRes>;

Expected behavior

I would expect, that the type is shown in the Swagger Docs even though it is nullable.

Environment

"@nestjs/common": "7.6.12",
"@nestjs/core": "7.6.12",
"@nestjs/swagger": "^4.7.13",

[Tony133]

Hi @zaunermax, I recommend that you leave a minimal reproduction of a clonable git repository so that the core team can evaluate the problem you reported.

[kamilmysliwiec]

Nullable is a generic type.

Since TypeScript does not store metadata about generics or interfaces, when you use them in your DTOs, SwaggerModule may not be able to properly generate model definitions at runtime.

https://docs.nestjs.com/openapi/types-and-parameters#generics-and-interfaces

[zaunermax]

@kamilmysliwiec I know that, but I thought the type information comes from the annotation and there I did NOT use the Nullable type. It's merely the options object that causes the bug - I can leave in the Nullable type and it works, but removing nullable: true from the annotation fixes the issue, so clearly not a type issue...

[zaunermax]

@Tony133 I will, once I have time :raised_hands: I just encountered this bug @ work - so I thought I might report it.

[kamilmysliwiec]

Ah I haven't noticed the explicit type definition in the annotation @zaunermax. Let me reopen this issue.

Can you please provide a minimal reproduction repository?

[zaunermax]

@kamilmysliwiec I added a test repro repo here

you can see, the reference is broken in this screenshot when looking at the api documentation

[zaunermax]

I tried to research this a bit and stumbled upon this issue. Seems to be a known problem of the openapi spec 3.0.*

When using nullable, a schema combination of nullable and allOf is created:

"nested": {
  "nullable": true,
  "allOf": [
    { "$ref": "#/components/schemas/NestedDTO" },
  ]
}

which seems to be a common practise but is wrong according to the specification (according to people in the linked issue) - therefore the openapi swagger ui does not display that correctly or not at all.

It seems that the openapi spec 3.1.* got rid of nullable alltogether so one could write smth like that:

"nested": {
  "oneOf": [
    { type: "null" },
    { "$ref": "#/components/schemas/NestedDTO" }
  ]
}

I am therefore not sure, if this issue is still actionable or not. One suggestion could be to switch allOf to oneOf which is kind of "weird" but at least it shows the referenced type :thinking:

"nested": {
  "nullable": true,
  "oneOf": [
    { "$ref": "#/components/schemas/NestedDTO" },
  ]
}

[lkostrowski]

Hi @kamilmysliwiec , is there any plan to bump this package to OAS 3.1?