Model nullable types using allOf in OpenAPI schema

[captainsafia]

This PR updates the schema generation logic to use allOf schemas with nullable to model nullable types in responses, request bodies, and properties. This allows us to emit singular unannotated types into components.schemas and mark them as nullabe at the site where they are used.

Before/After Examples

Request Bodies

Before (union type):

{
  "requestBody": {
    "content": {
      "application/json": {
        "schema": {
          "$ref": "#/components/schemas/Todo" // Todo is ["object", "null"]
        }
      }
    }
  }
}

After (allOf approach):

  {
    "requestBody": {
      "content": {
        "application/json": {
          "schema": {
            "allOf": [
              {
                "type": "null"
              },
              {
                "$ref": "#/components/schemas/Todo" // Todo is "type": "object"
              }
            ]
          }
        }
      }
    }
  }

Properties

Before:

  {
    "properties": {
      "secondaryUser": {
        "$ref": "#/components/schemas/RefProfile" // RefProfile is ["object", "null"]
      }
    }
  }

After:

  {
    "properties": {
      "secondaryUser": {
        "allOf": [
          {
            "type": "null"
          },
          {
            "$ref": "#/components/schemas/RefProfile" // RefProfile is "type": "object"
          }
        ]
      }
    }
  }

Responses

Before:

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

After:

  {
    "responses": {
      "200": {
        "content": {
          "application/json": {
            "schema": {
              "allOf": [
                { "type": "null" },
                { "$ref": "#/components/schemas/SomeModel" }
              ]
            }
          }
        }
      }
    }
  }

The implementation uses NullabilityInfoContext to detect nullability for the following .NET runtime elements and their related OpenAPI concents

The implementation uses NullabilityInfoContext to determine nullability for:

• Method parameters (via ParameterInfo) which map to request parameters
• Method return types (via ReturnParameter) which map to response types
• Properties (via PropertyInfo) which map to properties within complex types

There are some scenarios where it is impossible to determine the nullability of a type at runtime given runtime restrictions. In those cases, we emit a non-nullable schemas. For example, nullability info cannot be resolved for reference types as array element types:

// This will still encode as non-nullable even though declared as string?[]
app.MapGet("/", (string?[] inputs) => { });

[Copilot]

Pull Request Overview

This PR updates the OpenAPI schema generation logic to use allOf schemas with nullable types to model nullable types in responses, request bodies, and properties. This approach allows generating clean, unannotated component schemas while handling nullability at usage sites.

• Updates schema generation to use allOf with a null type and a reference to the base schema for nullable types
• Replaces the previous union type approach (["object", "null"]) with allOf containing { "type": "null" } and the base schema reference
• Uses NullabilityInfoContext to detect nullability for method parameters, return types, and properties

Reviewed Changes

Copilot reviewed 17 out of 17 changed files in this pull request and generated 3 comments.

Show a summary per file

File	Description
OpenApiSchemaReferenceTransformerTests.cs	Updates test assertions to verify allOf nullable schema structure instead of union types
OpenApiSchemaService.ResponseSchemas.cs	Adds comprehensive tests for nullable response schemas using allOf pattern
OpenApiSchemaService.RequestBodySchemas.cs	Adds tests for nullable request body parameters with allOf verification
OpenApiSchemaService.PropertySchemas.cs	New test file for nullable property schemas using allOf or direct null type inclusion
OpenApiSchemaService.ParameterSchemas.cs	Updates parameter schema tests and adds nullable complex type tests
Snapshot files	Updates expected OpenAPI document outputs to reflect new allOf nullable schema format
OpenApiSchemaService.cs	Adds logic to wrap nullable properties with allOf and prune null types from componentized schemas
OpenApiDocumentService.cs	Updates response and request body generation to apply nullable wrappers
OpenApiConstants.cs	Adds constant for nullable property metadata
OpenApiJsonSchema.Helpers.cs	Adds support for reading nullable property metadata
TypeExtensions.cs	Adds methods to determine nullability for responses, requests, and properties
OpenApiSchemaExtensions.cs	New extension methods to create allOf nullable wrappers
JsonTypeInfoExtensions.cs	Updates schema reference ID generation for nullable value types
JsonNodeSchemaExtensions.cs	Updates nullability handling and adds logic to prune null types from componentized schemas
MapSchemasEndpoints.cs	Adds sample endpoints demonstrating nullable schema behavior