Serializer Support

To generate accurate schemas for requestBody and response definitions, Swashbuckle needs to take serializer behavior into account. It currently supports the two most commonly used serializers - System.Text.Json and Newtonsoft.Json.

System.Text.Json (STJ)

By default, Swashbuckle will generate schemas based on the STJ serializer. This means it will honor the configured serializer behavior (i.e. JsonSerializerOptions) and the serialization attributes from the System.Text.Json.Serialization namespace. For example, given the following configuration and model classes:

Swashbuckle will generate the following schemas:

Newtonsoft.Json

If your application uses the Newtonsoft serializer, you should configure Swashbuckle to honor it’s behavior instead of STJ. To do this, follow the steps below:

1. Install the Swashbuckle.AspNetCore.Newtonsoft package:

   > dotnet add package Swashbuckle.AspNetCore.Newtonsoft
   

   or via Package Manager …

   > Install-Package Swashbuckle.AspNetCore.Newtonsoft
   

2. Explicitly opt-in by calling AddSwaggerGenNewtonsoftSupport in Startup.cs

Now, Swashbuckle will honor the configured Newtonsoft behavior (i.e. JsonSerializerSettings) and the serialization attributes from the Newtonsoft.Json namespace. For example, given the configuration above and the following model classes:

Swashbuckle will generate the following schemas: