microsoft / microsoft/OpenAPI.NET

Regression: broken nullability after update to v3.9.0

Open
#2,967 18 comments 1 reaction 0 assignees View on GitHub

Nobody has claimed this yet.

help wanted type:feature
Dominant language
C#
Stars
1.6k
Forks
286
Avg merge
6h 38m
Merged PRs (30d)
35

Description

Describe the bug
After updating from v3.7.0 to v3.9.0, the nullable property disappears when writing an OpenAPI 3.0 document.

Repro steps

using Microsoft.OpenApi;

var metaSchema = new OpenApiSchema
{
    Type = JsonSchemaType.Object,
    AdditionalProperties = new OpenApiSchema
    {
        Type = JsonSchemaType.Null
    }
};

var baseSchema = new OpenApiSchema
{
    Type = JsonSchemaType.Object,
    Id = "base",
    Properties = new Dictionary<string, IOpenApiSchema>
    {
        ["id"] = new OpenApiSchema
        {
            Type = JsonSchemaType.String
        }
    }
};

var derivedSchema = new OpenApiSchema
{
    Type = JsonSchemaType.Null,
    AllOf = new List<IOpenApiSchema>
    {
        new OpenApiSchemaReference(baseSchema.Id)
    },
    Properties = new Dictionary<string, IOpenApiSchema>
    {
        ["kind"] = new OpenApiSchema
        {
            Type = JsonSchemaType.String
        }
    }
};

var doc = new OpenApiDocument();
doc.Components ??= new OpenApiComponents();
doc.Components.Schemas ??= new Dictionary<string, IOpenApiSchema>();
doc.Components.Schemas.Add("meta", metaSchema);
doc.Components.Schemas.Add("base", baseSchema);
doc.Components.Schemas.Add("derived", derivedSchema);

var result = await doc.SerializeAsJsonAsync(OpenApiSpecVersion.OpenApi3_0);
Console.WriteLine(result);

Using v3.7.0, this prints:

{
  "openapi": "3.0.4",
  "info": { },
  "paths": { },
  "components": {
    "schemas": {
      "meta": {
        "type": "object",
        "additionalProperties": {
          "nullable": true
        }
      },
      "base": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string"
          }
        }
      },
      "derived": {
        "allOf": [
          {
            "$ref": "#/components/schemas/base"
          }
        ],
        "properties": {
          "kind": {
            "type": "string"
          }
        },
        "nullable": true
      }
    }
  }
}

Using v3.9.0, this prints:

{
  "openapi": "3.0.4",
  "info": { },
  "paths": { },
  "components": {
    "schemas": {
      "meta": {
        "type": "object",
        "additionalProperties": {
          "enum": [
            null
          ]
        }
      },
      "base": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string"
          }
        }
      },
      "derived": {
        "allOf": [
          {
            "$ref": "#/components/schemas/base"
          }
        ],
        "properties": {
          "kind": {
            "type": "string"
          }
        }
      }
    }
  }
}

Screenshots/Code Snippets
View of the diff:

Image

Originally reported at: https://github.com/domaindrivendev/Swashbuckle.AspNetCore/issues/4065

Contributor guide

Open the contributing guide

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. Open a pull request that references the issue number.

Research direction

Start by running the supplied C# reproduction through SerializeAsJsonAsync(OpenApiSpecVersion.OpenApi3_0) and compare the v3.7.0 and v3.9.0 outputs. Trace OpenAPI 3.0 schema serialization for JsonSchemaType.Null in additionalProperties and an allOf-derived schema; done means nullable is preserved in both cases without changing the shown output for other fields.

Written by the indexing model from the issue text.

Assessment

Tech stack
csharp
Domain
api
Issue type
Bug
Difficulty
3/5
Estimated time
1-2 days
Activity status
Quiet
Clarity
Mostly clear
Newbie friendliness
55/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.