Incorrect open-api spec is generated for nullable value type properties

[fgheysels]

I have an API request model which looks like this:

public class MyRequestModel
{
     public MyEnum?  Rank { get; set; }

     public string Reason { get; set; }
}

public enum MyEnum
{
     None,
     First,
     Second
}

The Rank property is declared as a nullable, but in the generated swagger, the property is not declared as nullable:

"MyRequestModel": {
        "type": "object",
        "properties": {
          "rank": {
            "$ref": "#/components/schemas/MyEnum"
          },
          "reason": {
            "type": "string",            
            "nullable": true
          }
        },
        "additionalProperties": false
      }

However, as you can see, the Reason property which is of type string (reference type) is marked as nullable. The nullable enum property however is not.

This is an issue since we generate the OpenAPI spec file, and that file also contains Swagger Examples. This Open API spec file is used to import in Azure API Management, but API management gives back validation errors when trying to import this file, since the example that we include in the file has no value for the Rank property (which it shouldn't, since that property is nullable and not required in the model, but the swagger file doesn't indicate it as 'nullable')..

We're making use of swashbuckle.aspnetcore 5.5.1

[paulsavides]

There seems to be some context on this issue here #861 (comment)

[domaindrivendev]

@fgheysels the Rank property itself cannot include the nullable keyword because it uses a referenced schema definition. As per the JSONSchema a "reference" schema MUST NOT have any properties present other than the $ref property. This presents a bit of a dilemna. On the one hand you probably want enum schema's to be referenced as opposed to being redefined inline with every usage. But, if they're referenced then you can't really apply something "contextual" like nullable to the definition schema because it can be shared across different contexts. In fact, there's an issue in the Swagger/OpenAPI repo addressing this exact problem.

Swashbuckle gives you two options here. You can apply the suggested workaround from that issue with the UseAllOfToExtendReferenceSchemas() setting: This would generate the following JSON schema for your Rank property:

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

This is prob the best option but another alternative would be to force all enum schema's to be defined inline, rather than by reference, by setting UseInlineDefinitionsForEnums(). This would generate the following JSON for your Rank property

"rank": {
  "enum": [
    0,
    1,
    2
  ],
  "type": "integer",
  "format": "int32",
  "nullable": true
}