Nswag: SwaggerUI doesn't render example values for a non-enumerable types

[StasPerekrestov]

Hi,

It seems to me, there is an issue related to example values generation logic for asp.net controllers
when a controller returns a single value (in a case when OAS3 is used).

The screenshot relates to this code

However, if you just for the sake of experiment change the return type from

 [ProducesResponseType(typeof(Pet), StatusCodes.Status200OK)]
        [ProducesResponseType(typeof(SerializableError), StatusCodes.Status400BadRequest)]
        [ProducesResponseType(StatusCodes.Status404NotFound)]
        public async Task<ActionResult<Pet>> FindById(int petId)
        {

to

ProducesResponseType(typeof(IEnumerable<Pet>), StatusCodes.Status200OK)]
        [ProducesResponseType(typeof(SerializableError), StatusCodes.Status400BadRequest)]
        [ProducesResponseType(StatusCodes.Status404NotFound)]
        public async Task<ActionResult<IEnumerable<Pet>>> FindById(int petId)
        {

it generates the expected example value

[StasPerekrestov]

For the Pet definition NSwag generates something like:

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

I believe it should be

"responses": {
          "200": {
            "description": "",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Pet"
                }
              }
            }
          },
        }

Please have a look at a demo.

[RicoSuter]

Yes, this is because response reference types are nullable by default, see https://github.com/RicoSuter/NSwag/issues/2071

Try to set DefaultResponseReferenceTypeNullHandling to ReferenceTypeNullHandling.NotNull (maybe this should be the default - but it is not really correct and changing the default might break users)

[StasPerekrestov]

Oh, it looks like the issue relates to https://github.com/swagger-api/swagger-ui/issues/3803

[RicoSuter]

Yes, it's also a bug in Swagger UI:

As pointed out in https://github.com/RicoSuter/NSwag/issues/2071 we should create an issue there that this syntax to describe nullability is supported:

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

[RicoSuter]

Is this correctly supported in ReDoc?

[StasPerekrestov]

Yeah, actually I don't use ReDoc, however today I poked the issue from many perspectives and turned on ReDoc. Well, I was a bit surprised, because it renders the expected output.

[StasPerekrestov]

BTW, feel free to close the issue

[RicoSuter]

Yeah, ReDoc is nice but I think it still does not support executing (Try Out) the operation so not an option for lots of people

[RicoSuter]

But could you solve your problem?

[StasPerekrestov]

Hm, something weird happens. It worked when I used a local build of NSwag.AspNetCore (from sources).
However, I cannot make it work using nuget 12.2.5. I'll give it another chance later today.

[RicoSuter]

There are no more commits after the v12.2.5 in master ATM

[StasPerekrestov]

Quite odd, recompiled with dll built from latest sources - it works. And it doesn't work with nuget packages. Mystique...

[RicoSuter]

The spec (JSON) is the same? Can you describe the diff?

[StasPerekrestov]

[RicoSuter]

And what is the value of DefaultResponseReferenceTypeNullHandling? With NotNull it should not produce oneOf, is that correct?

Commit: https://github.com/RicoSuter/NSwag/commit/86a7d09a7eab6c97ca54b8fb7f064158878c668d

Are you locally using NSwag via NSwag.AspNetCore or the compiled CLI/NSwagStudio, etc because correctly compiling the CLI/UI is hard :-)?

[StasPerekrestov]

Yeah :), I'm using
_NSwag\src\NSwag.AspNetCore_
dotnet build -f netstandard2.0 to build it locally

BTW, I've created a demo repo https://github.com/StasPerekrestov/NSwagIssueDemo
document.DefaultReferenceTypeNullHandling = ReferenceTypeNullHandling.NotNull; is set

So, the example value isn't still generated by swagger UI, and reDoc displays the correct result.

{
  "x-generator": "NSwag v12.2.5.0 (NJsonSchema v9.13.37.0 (Newtonsoft.Json v11.0.0.0))",
  "openapi": "3.0.0",
 ...
  "paths": {
    "/api/Values/{id}": {
      "get": {
        "tags": [
          "Values"
        ],
        "operationId": "Values_Get",
        "parameters": [
          {
            "name": "id",
            "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/MyDto"
                    }
                  ]
                }
...        
}

[StasPerekrestov]

Oh, my fault, sorry.
I used
t.DefaultReferenceTypeNullHandling = ReferenceTypeNullHandling.NotNull;
instead of
t.DefaultResponseReferenceTypeNullHandling = ReferenceTypeNullHandling.NotNull;

[RicoSuter]

@StasPerekrestov please have a look at this PR: https://github.com/RicoSuter/NSwag/pull/2215