Response types using Nullable/oneOf are invisible in swagger-ui (OpenApi3)

[softworkz]

This can be seen for example in NSwag.Sample.NETCore22 (unmodified):

Operation /pet/{petId}:

Definition:

    "/pet/{petId}": {
      "get": {
        "tags": [
          "Pet"
        ],
        "operationId": "Pet_FindById",
        "parameters": [
          {
            "name": "petId",
            "in": "path",
            "required": true,
            "schema": {
              "type": "integer",
              "format": "int32"
            },
            "x-position": 1
          }
        ],
        "responses": {
          "200": {
            "description": "",
            "content": {
              "application/json": {
                "schema": {
                  "nullable": true,
                  "oneOf": [
                    {
                      "$ref": "#/components/schemas/Pet"
                    }
                  ]
                }
              }
            }
          },

The schemas for the other responses are visible because they are array types. But the problem exists for all single object return types.

The only workaround I found is

config.DefaultReferenceTypeNullHandling = ReferenceTypeNullHandling.NotNull;
But that doesn't seem to be a good solution...

[RicoSuter]

Just nice, how are we supposed to express a nullable Pet otherwise?

[RicoSuter]

See: https://stackoverflow.com/a/48114924/876814 (they use allOf - we could use that too)

But maybe we need to raise an issue in Swagger UI to fix that?

[RicoSuter]

Ref: OAI/OpenAPI-Specification#1368

@handrews is this:

"application/json": {
  "schema": {
    "nullable": true,
    "oneOf": [
      {
        "$ref": "#/components/schemas/Pet"
      }
    ]
  }
}

the correct syntax for referencing a nullable Pet - or must we use "allOf"?

[softworkz]

The other question besides this is whether it makes sense that a response will be indicated as nullable when it's a reference type (C# class) and non-nullable when it's a value type.

That inference doesn't make a lot of sense to me because whether the API may return an empty response or not is not a matter of value-type vs. reference-type.

[handrews]

@RicoSuter when there is only one entry, oneOf, anyOf, and allOf are effectively identical. I use allOf because it's semantics are arguably the simplest and probably have the broadest tooling support.

@softworkz I prefer to leave out irrelevant fields rather than sending literal nulls. It works better with JSON Merge Patch if you decide to use that. And if you are consistent about never using JSON null, strongly typed languages can fill in appropriate null values as needed, and strip them out on serialization. But that's just my stylistic preference.

[softworkz]

@handrews - I wasn't referring to nullable fields inside a schema. In this case, it's just about the root response object itself.

[handrews]

@softworkz Oh, I see. When you say that the root response could be nullable do you man that the response would be an application/json document consisting just of a JSON null literal? I would probably just use a 204 No Content as a possible response instead.

[RicoSuter]

I would probably just use a 204 No Content as a possible response instead.

That is correct - but ASP.NET Core will send a null with status 200 in this case - 204 with no content has to be implemented manually...

So in theory this nullable + oneOf should be displayed correctly in Swagger UI - @softworkz can you open an issue in the Swagger UI repo (and reference this issue)?

[RicoSuter]

@handrews thanks for your fast answer!

[softworkz]

Would this be fixed by using allOf? I haven't tried yet...

[handrews]

That is correct - but ASP.NET Core will send a null with status 200 in this case - 204 with no content has to be implemented manually...

LOL. I hate strongly typed languages with inflexible frameworks 😝

[softworkz]

I love strong typing..

Thanks a lot for your advise, though!

[RicoSuter]

I love strong typing..

Yeah me too :-)

BTW: With C# 8's Nullable Reference Types the default will be non nullable for this return - and only if you add ? to the type it will produce this null + oneOf, for more information, see https://blog.rsuter.com/the-output-of-nullable-reference-types-and-how-to-reflect-it/

[softworkz]

I've read about it. But this behavior can't be introduced to existing projects. At least I can't imagine how this could work..

[RicoSuter]

As soon as you enable the feature the whole JSON Schema/OpenAPI generator would behave as if

config.DefaultReferenceTypeNullHandling = ReferenceTypeNullHandling.NotNull; 

were set... and to make something nullable you'd need to add MyType? like you can do already with primitive types (e.g. int?). But enabling this in an existing project might produce breaking changes in the spec and yield lots of compile warnings.