Releases: domaindrivendev/Swashbuckle.AspNetCore
v5.6.0
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:
- Improve polymorphism & inheritance behavior, incl. more flexible config & discriminator metadata
- Better support for reverse proxy environments, incl. assigning
serversmetadata based on the presence of common reverse proxy headers - Support for emitting Swagger / OpenAPI in yaml format
- Improve Schema generation for
ProblemDetails - Handle Min/MaxLength attribute for arrays
- Upgrade swagger-ui to v3.32.5
- Upgrade redoc to v2.0.0-rc.40
v5.5.0
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
v5.4.1
v5.4.0
v5.3.0
v5.2.0
V5.1.0
Issues Addressed
See https://github.com/domaindrivendev/Swashbuckle.AspNetCore/milestone/9?closed=1
v5.0.0
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
- New Swagger/OpenAPI Object Model:
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);
- Honors System.Text.Json Serializer instead of Newtonsoft by default:
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
- Changes to Filter Interfaces
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
Last planned pre-release
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
- New Swagger/OpenAPI Object Model:
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);
- Honors System.Text.Json Serializer instead of Newtonsoft by default:
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
- Changes to Filter Interfaces
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
Last planned pre-release before 5.0.0
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
- New Swagger/OpenAPI Object Model:
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);
- Changes to Filter Interfaces
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