NewYour coding agent can read the release notes before it upgrades.Set up the MCP server →
NuGet, #39 most downloaded on NuGet
Middleware to expose an embedded version of the swagger-ui from an ASP.NET Core application
Latest stable
11.0.1
Last release 8 days ago
12 Nov 2026
Release timing varies
gaps range from 2 weeks to 4 months
Most releases are documented
notes for 51 of the last 60 stable releases
4 versions withdrawn
withdrawn after publishing
127 years old
108 releases · first in 1900
Drag across the ruler to compare, or tap a release to open it.
Nothing published for this version
Nothing published for this version
Nothing published for this version
Nothing published for this version
Nothing published for this version
Your coding agent can read these notes before it upgrades. Set up the MCP server →
Nothing published for this version
Nothing published for this version
Nothing published for this version
remove fragile logic around X-Forwarded-* headers in favor of MS's Forwarded Headers Middleware (*see breaking changes)
This release includes a number of small enhancements and bug fixes. See the following for a full list of issues addressed: https://github.com/domaindrivendev/Swashbuckle.AspNetCore/milestone/16?closed=1
Of note, these include:
Breaking Changes
DescribeAllEnumsAsStrings and DescribeStringEnumsInCamelCase are now fully removedNothing published for this version
Nothing published for this version
Nothing published for this version
This release includes a number of small enhancements and bug fixes. See the following for a full list of issues addressed: https://github.com/domaindr
This release includes a number of small enhancements and bug fixes. See the following for a full list of issues addressed: https://github.com/domaindrivendev/Swashbuckle.AspNetCore/milestone/15?closed=1
Of note, these include:
servers metadata based on the presence of common reverse proxy headersProblemDetailsNothing published for this version
These release is primarily to improve compatability of the CLI tool with different versions of the dotnet SDK, but also contains a few other minor fix
These release is primarily to improve compatability of the CLI tool with different versions of the dotnet SDK, but also contains a few other minor fixes and enhancements, including an upgrade of the embedded swagger-ui to version 3.26.0.
Addressed issues:
https://github.com/domaindrivendev/Swashbuckle.AspNetCore/milestone/14?closed=1
Nothing published for this version
https://github.com/domaindrivendev/Swashbuckle.AspNetCore/milestone/13?closed=1
Issues Addressed:
https://github.com/domaindrivendev/Swashbuckle.AspNetCore/milestone/13?closed=1
Nothing published for this version
Nothing published for this version
Nothing published for this version
__Issues Addressed__ https://github.com/domaindrivendev/Swashbuckle.AspNetCore/milestone/12?closed=1
Issues Addressed https://github.com/domaindrivendev/Swashbuckle.AspNetCore/milestone/12?closed=1
Nothing published for this version
__Issues Addressed__ https://github.com/domaindrivendev/Swashbuckle.AspNetCore/milestone/10
Issues Addressed https://github.com/domaindrivendev/Swashbuckle.AspNetCore/milestone/10
See https://github.com/domaindrivendev/Swashbuckle.AspNetCore/milestone/9?closed=1
Issues Addressed
See https://github.com/domaindrivendev/Swashbuckle.AspNetCore/milestone/9?closed=1
This release contains a number of significant changes, including a transition to Swagger/OpenAPI v3 and support for ASP.NET Core 3.0, and will require
Release Summary
This release contains a number of significant changes, including a transition to Swagger/OpenAPI v3 and support for ASP.NET Core 3.0, and will require modifications to your application setup if you're upgrading from previous major versions.
While it's awesome to finally support the latest Swagger/OpenAPI version (v3), this does introduce significant structural changes to the Swagger object model, which you're likely interacting with to configure and/or extend Swashbuckle. Specific details are provided below but at a high level, the built-in SwaggerDocument and contained types have now been replaced with an OpenApiDocument object model that's imported from the Micorosft/OpenAPI.NET library.
To coincide with the release of ASP.NET Core 3.x, this version of Swashbuckle will be fully compatible with that version of the framework, including out-of-the-box support for the new System.Text.Json (STJ) serializer.
Furthermore, this release also includes a wide range of bug fixes and enhancements including an upgrade of the embedded swagger-ui to 3.24.3, an upgrade of the ReDoc UI to 2.0.0-rc.14, improved handling of IFormFile and FileResult parameters and responses, and support for polymorphic models.
Breaking Changes
Best case, you can simply replace references to the old Swagger objects (Info, Operation, Schema etc.) with corresponding types from the new object model (e.g. OpenApiInfo, OpenApiOperation, OpenApiSchema) available in the Microsoft.OpenApi.Models namespace. However, the old model was based on version 2.0 of the Swagger/OpenApi spec. whereas the new version is based on 3.0. Therefore, depending on the extent to which you're manipulating the generated Swagger, you may need to re-work some of your code. Check out the official Swagger docs to get a better sense of what's changed between v2 and v3 of the spec.
It's also worth noting ... if you have consumers of the generated Swagger JSON that still depend on v2 of the spec, you can configure the Swagger middleware to continue outputting in that format:
app.UseSwagger(c => c.SerializeAsV2 = true);
While previous versions of Swashbuckle honored Newtonsoft settings/attributes by default when generating Swagger, this version honors STJ options/attributes by default. If you're still using the Newtonsoft serializer, then you'll need to install a separate Swashbuckle package and explicitly opt-in as described here
As a result of the object model change, the Apply method for all filter types accepts a type from the new model instead of the old. For example, IOperationFilter.Apply now accepts an OpenApiOperation, IParameterFilter.Apply an OpenApiParameter and so on.
Also, the SchemaRegistry property on filter context objects has been replaced with a SchemaGenerator/SchemaRepository pair of properties. This change is the result of an underlying separating of concerns into "schema generation" and "referenced schema storage". Now, if you need to leverage the schema generator within a filter, it should be invoked as follows:
var schema = context.SchemaGenerator.GenerateSchema(typeof(CustomType), context.SchemaRepository);
Issues Addressed
See https://github.com/domaindrivendev/Swashbuckle.AspNetCore/milestone/7?closed=1
This release contains a number of significant changes, including a transition to Swagger/OpenAPI v3 and support for ASP.NET Core 3.0, and will require
Release Summary
This release contains a number of significant changes, including a transition to Swagger/OpenAPI v3 and support for ASP.NET Core 3.0, and will require modifications to your application setup if you're upgrading from previous major versions.
While it's awesome to finally support the latest Swagger/OpenAPI version (v3), this does introduce structural changes to the Swagger object model, which you're likely interacting with to configure and/or extend Swashbuckle. Specific details are provided below but at a high level, the built-in SwaggerDocument and contained types have now been replaced with an OpenApiDocument object model that's imported from the Micorosft/OpenAPI.NET library.
To coincide with the release of ASP.NET Core 3.x, this version of Swashbuckle will be fully compatible with that version of the framework, including out-of-the-box support for the new System.Text.Json (STJ) serializer.
Furthermore, this release also includes a wide range of bug fixes and enhancements including an upgrade of the embedded swagger-ui to 3.24.0, an upgrade of the ReDoc UI to 2.0.0-rc.14, improved handling of IFormFile and FileResult parameters and responses, and support for polymorphic models.
Breaking Changes
Best case, you can simply replace references to the old Swagger objects (Info, Operation, Schema etc.) with corresponding types from the new object model (e.g. OpenApiInfo, OpenApiOperation, OpenApiSchema) available in the Microsoft.OpenApi.Models namespace. However, the old model was based on version 2.0 of the Swagger/OpenApi spec. whereas the new version is based on 3.0. Therefore, depending on the extent to which you're manipulating the generated Swagger, you may need to re-work some of your code. Check out the official Swagger docs to get a better sense of what's changed between v2 and v3 of the spec.
It's also worth noting ... if you have consumers of the generated Swagger JSON that still depend on v2 of the spec, you can configure the Swagger middleware to continue outputting in that format:
app.UseSwagger(c => c.SerializeAsV2 = true);
While previous versions of Swashbuckle honored Newtonsoft settings/attributes by default when generating Swagger, this version honors STJ options/attributes by default. If you're still using the Newtonsoft serializer, then you'll need to install a separate Swashbuckle package and explicitly opt-in as described here
As a result of the object model change, the Apply method for all filter types accepts a type from the new model instead of the old. For example, IOperationFilter.Apply now accepts an OpenApiOperation, IParameterFilter.Apply an OpenApiParameter and so on.
Also, the SchemaRegistry property on filter context objects has been replaced with a SchemaGenerator/SchemaRepository pair of properties. This change is the result of an underlying separating of concerns into "schema generation" and "referenced schema storage". Now, if you need to leverage the schema generator within a filter, it should be invoked as follows:
var schema = context.SchemaGenerator.GenerateSchema(typeof(CustomType), context.SchemaRepository);
Issues Addressed
See https://github.com/domaindrivendev/Swashbuckle.AspNetCore/milestone/7?closed=1
This release contains a number of significant changes, including a transition to Swagger/OpenAPI v3 and support for ASP.NET Core 3.0, and will require
Release Summary
This release contains a number of significant changes, including a transition to Swagger/OpenAPI v3 and support for ASP.NET Core 3.0, and will require modifications to your application setup if you're upgrading from previous major versions.
While it's awesome to finally support the latest Swagger/OpenAPI version (v3), this does introduce structural changes to the Swagger object model, which you're likely interacting with to configure and/or extend Swashbuckle. Specific details are provided below but at a high level, the built-in SwaggerDocument and contained types have now been replaced with an OpenApiDocument object model that's imported from the Micorosft/OpenAPI.NET library.
To coincide with the ASP.NET Core 3.0 release in Sep 2019, this version of Swashbuckle will be fully compatible with that version of the framework. At this point, the schema generator is still optimized for Newtonsoft serializer behaviors but additional support for the new System.Text.Json API is planned for a future minor version.
Furthermore, this release also includes a wide range of bug fixes and enhancements including an upgrade of the embedded swagger-ui to 3.23.8, an upgrade of the ReDoc UI to 2.0.0-rc.14, improved handling of IFormFile and FileResult parameters and responses, and support for polymorphic models.
Breaking Changes
Best case, you can simply replace references to the old Swagger objects (Info, Operation, Schema etc.) with corresponding types from the new object model (e.g. OpenApiInfo, OpenApiOperation, OpenApiSchema) available in the Microsoft.OpenApi.Models namespace. However, the old model was based on version 2.0 of the Swagger/OpenApi spec. whereas the new version is based on 3.0. Therefore, depending on the extent to which you're manipulating the generated Swagger, you may need to re-work some of your code. Check out the official Swagger docs to get a better sense of what's changed between v2 and v3 of the spec.
It's also worth noting ... if you have consumers of the generated Swagger JSON that still depend on v2 of the spec, you can configure the Swagger middleware to continue outputting in that format:
app.UseSwagger(c => c.SerializeAsV2 = true);
As a result of the object model change, the Apply method for all filter types accepts a type from the new model instead of the old. For example, IOperationFilter.Apply now accepts an OpenApiOperation, IParameterFilter an OpenApiParameter and so on.
Also, the SchemaRegistry property on filter context objects has been replaced with a SchemaGenerator/SchemaRepository pair of properties. This change is the result of an underlying separating of concerns into "schema generation" and "referenced schema storage". Now, if you need to leverage the schema generator within a filter, it should be invoked as follows:
var schema = context.SchemaGenerator.GenerateSchema(typeof(CustomType), context.SchemaRepository);
Finally, the SystemType and JsonContract properties on SchemaFiltercontext have been replaced with a new property of name and type ApiModel. Like JsonContract, this abstracts serializer behavior for a given type, but without coupling to the Newtonsoft library directly, making it easier to support other serializers (e.g. System.Text.Json) going forward. If you need access to the underlying type, use ApiModel.Type instead of SystemType.
Issues Addressed
See https://github.com/domaindrivendev/Swashbuckle.AspNetCore/milestone/7?closed=1
This release contains a number of significant changes, including a transition to Swagger/OpenAPI v3 and support for ASP.NET Core 3.0, and will require
Release Summary
This release contains a number of significant changes, including a transition to Swagger/OpenAPI v3 and support for ASP.NET Core 3.0, and will require modifications to your application setup if you're upgrading from previous major versions.
While it's awesome to finally support the latest Swagger/OpenAPI version (v3), this does introduce structural changes to the Swagger object model, which you're likely interacting with to configure and/or extend Swashbuckle. Specific details are provided below but at a high level, the built-in SwaggerDocument and contained types have now been replaced with an OpenApiDocument object model that's imported from the Micorosft/OpenAPI.NET library.
To coincide with the ASP.NET Core 3.0 release in Sep 2019, this version of Swashbuckle will be fully compatible with that version of the framework. At this point, the schema generator is still optimized for Newtonsoft serializer behaviors but additional support for the new System.Text.Json API is planned for a future minor version.
Furthermore, this release also includes a wide range of bug fixes and enhancements including an upgrade of the embedded swagger-ui to 3.23.8, an upgrade of the ReDoc UI to 2.0.0-rc.14, improved handling of IFormFile and FileResult parameters and responses, and support for polymorphic models.
Breaking Changes
Best case, you can simply replace references to the old Swagger objects (Info, Operation, Schema etc.) with corresponding types from the new object model (e.g. OpenApiInfo, OpenApiOperation, OpenApiSchema) available in the Microsoft.OpenApi.Models namespace. However, the old model was based on version 2.0 of the Swagger/OpenApi spec. whereas the new version is based on 3.0. Therefore, depending on the extent to which you're manipulating the generated Swagger, you may need to re-work some of your code. Check out the official Swagger docs to get a better sense of what's changed between v2 and v3 of the spec.
It's also worth noting ... if you have consumers of the generated Swagger JSON that still depend on v2 of the spec, you can configure the Swagger middleware to continue outputting in that format:
app.UseSwagger(c => c.SerializeAsV2 = true);
As a result of the object model change, the Apply method for all filter types accepts a type from the new model instead of the old. For example, IOperationFilter.Apply now accepts an OpenApiOperation, IParameterFilter an OpenApiParameter and so on.
Also, the SchemaRegistry property on filter context objects has been replaced with a SchemaGenerator/SchemaRepository pair of properties. This change is the result of an underlying separating of concerns into "schema generation" and "referenced schema storage". Now, if you need to leverage the schema generator within a filter, it should be invoked as follows:
var schema = context.SchemaGenerator.GenerateSchema(typeof(CustomType), context.SchemaRepository);
Finally, the SystemType and JsonContract properties on SchemaFiltercontext have been replaced with a new property of name and type ApiModel. Like JsonContract, this abstracts serializer behavior for a given type, but without coupling to the Newtonsoft library directly, making it easier to support other serializers (e.g. System.Text.Json) going forward. If you need access to the underlying type, use ApiModel.Type instead of SystemType.
Issues Addressed
See https://github.com/domaindrivendev/Swashbuckle.AspNetCore/milestone/7?closed=1
Nothing published for this version
Nothing published for this version
Nothing published for this version
Nothing published for this version
This release makese an explicit jump to ASP.NET Core 2.0 and the netstandard2.0 library contract. As a result, Swashbuckle can simplify it's implement
Release Summary
This release makese an explicit jump to ASP.NET Core 2.0 and the netstandard2.0 library contract. As a result, Swashbuckle can simplify it's implementation by leveraging some of the newer ASP.NET Core features. However, it also means applications need to upgrade their ASP.NET Core stack to 2.0 or above before they can use this version or subsequent versions of Swashbuckle.
It also includes a significant refactor to the way in which Swashbuckle middleware and services are configured, adhering more closely to the ASP.NET Core Options Pattern. This allows for the Swashbuckle components to be configured via appSettings.json if desired.
The other notable change with this release is out-of-the-box support for parameters of type IFormFile. That is, the generator will automatically detect these and generate the correct Swagger to describe parameters that are passed in formData. If you have a workaround in place (e.g. using Operation Filters), you should remove it as part of the upgrade.
Breaking Changes
Requires ASP.NET Core 2.0 and netstandard2.0 or above: Applications need to upgrade their ASP.NET Core stack to 2.0 or above before they can use this version or subsequent versions of Swashbuckle.
Strongly typed options for SwaggerUI and ReDoc middleware:
May need to update middleware configuration (e.g. in Startup.cs) to compile
Explicit OperationIds now required:
As per the Swagger spec, operationIds MUST be unique and SHOULD follow common programming conventions. In previous versions, Swashbuckle attempted to generate these values but this has proved increasingly problematic. As a result, this behavior has been removed and the action name or (optionally) the route name is used instead. So, API developers are now responsible to ensure the uniqueness of these values. See the readme topic for more details.
Issues Addressed
See https://github.com/domaindrivendev/Swashbuckle.AspNetCore/milestone/6?closed=1
__Release Summary__ Includes two significant changes in addition to a handful of bug fixes and minor enhancements. The generator will now honor the Bi
Release Summary
Includes two significant changes in addition to a handful of bug fixes and minor enhancements. The generator will now honor the BindRequired and Required attributes on ALL parameters (top-level or property-based) and model properties, flagging the corresponding elements as required in the generated Swagger. Also, the Swagger-specific annotations (SwaggerOperation, SwaggerResponse etc.) have been enhanced, but also extracted from the core functionality into a separate package that consumers need to explicitly install and enable.
Breaking Changes
Swashbuckle.AspNetCore.Annotations package as described here. Furthermore, the attributes have moved from the SwaggerGen namespace to the Annotations namespace, and the ordering of some constructor parameters has changed. So, you'll need to update and test your use of these attributes.Required / BindRequired attributes: Previously, parameters and properties had to be decorated with these attributes AND be nullable to be flagged as required in the generated Swagger. This has changed and now those attributes will be honored on ALL parameters and model properties.Issues Addressed See https://github.com/domaindrivendev/Swashbuckle.AspNetCore/milestone/5?closed=1
Nothing published for this version
Set parameter required based on model binding & data validation behavior
Add options to use references for enum definitions
Nothing published for this version
Nothing published for this version
disables UI validator badge by default
upgrades embedded version of swagger-ui from 2.2.10 to 3.10.0 . This involves breaking changes to the SwaggerUI config interface - see readme for deta…
dotnet-swagger to Swashbuckle.AspNetCore.Clinew package for embedded Redoc as an alternative to swagger-ui
Fixes #288, #318, #336, #389, #402, #425, #523
Fixes #288, #318, #336, #389, #402, #425, #523
Nothing published for this version
(Hopefully) the last RC before a stable release which will follow shortly assuming no major issues.
(Hopefully) the last RC before a stable release which will follow shortly assuming no major issues.
Addresses: #171, #249, #255, #266, #267, #274, #305
Breaking Changes:
Nothing published for this version
Nothing published for this version
Nothing published for this version
One column per quarter.