| đź“Ł Important notice if you're upgrading between major versions! |
|---|
| * If you're upgrading from 4.x to 5.x, there's several breaking changes to be aware of. See the release notes for details * If you're making the jump from 3.x to 4.x first, there be dragons there too. See those release notes here |
Swagger tooling for APIs built with ASP.NET Core. Generate beautiful API documentation, including a UI to explore and test operations, directly from your routes, controllers and models.
In addition to its Swagger 2.0 and OpenAPI 3.0 generator, Swashbuckle also provides an embedded version of the awesome swagger-ui that's powered by the generated Swagger JSON. This means you can complement your API with living documentation that's always in sync with the latest code. Best of all, it requires minimal coding and maintenance, allowing you to focus on building an awesome API.
And that's not all ...
Once you have an API that can describe itself in Swagger, you've opened the treasure chest of Swagger-based tools including a client generator that can be targeted to a wide range of popular platforms. See swagger-codegen for more details.
| Swashbuckle Version | ASP.NET Core | Swagger / OpenAPI Spec. | swagger-ui | Redoc UI |
|---|---|---|---|---|
| CI | >= 8.0.0, 2.3.x | 2.0, 3.0 | 5.x.x | 2.x.x |
| 8.1.1 | >= 8.0.0, 2.3.x | 2.0, 3.0 | 5.20.8 | 2.4.0 |
| 7.3.2 | >= 8.0.0, 6.0.x, 2.1.x | 2.0, 3.0 | 5.20.1 | 2.4.0 |
| 6.9.0 | >= 6.0.0, 2.1.x | 2.0, 3.0 | 5.17.14 | 2.1.5 |
| 5.6.3 | >= 2.0.0 | 2.0, 3.0 | 3.32.5 | 2.0.0-rc.40 |
| 4.0.0 | >= 2.0.0, < 3.0.0 | 2.0 | 3.19.5 | 1.22.2 |
| 3.0.0 | >= 1.0.4, < 3.0.0 | 2.0 | 3.17.1 | 1.20.0 |
| 2.5.0 | >= 1.0.4, < 3.0.0 | 2.0 | 3.16.0 | 1.20.0 |
-
Install the standard Nuget package into your ASP.NET Core application.
Package Manager : Install-Package Swashbuckle.AspNetCore CLI : dotnet add package Swashbuckle.AspNetCore -
In the
ConfigureServicesmethod ofStartup.cs, register the Swagger generator, defining one or more Swagger documents.using Microsoft.OpenApi.Models;
services.AddMvc(); services.AddSwaggerGen(c => { c.SwaggerDoc("v1", new OpenApiInfo { Title = "My API", Version = "v1" }); });
-
Ensure your API actions and parameters are decorated with explicit "Http" and "From" bindings.
[HttpPost] public void CreateProduct([FromBody]Product product) ...
[HttpGet] public IEnumerable<Product> SearchProducts([FromQuery]string keywords) ...
NOTE: If you omit the explicit parameter bindings, the generator will describe them as "query" params by default.
-
In the
Configuremethod,you should expose the generated Swagger as JSON endpoint(s) by one of following method:- Add endpoints if you're using endpoint-based routing.
app.MapEndpoints(endpoints => { // ... endpoints.MapSwagger(); });
- Insert middleware
app.UseSwagger();
At this point, you can spin up your application and view the generated Swagger JSON at "/swagger/v1/swagger.json."
-
Optionally, insert the swagger-ui middleware if you want to expose interactive documentation, specifying the Swagger JSON endpoint(s) to power it from.
app.UseSwaggerUI(c => { c.SwaggerEndpoint("v1/swagger.json", "My API V1"); });
Now you can restart your application and check out the auto-generated, interactive docs at "/swagger".
In versions prior to 5.0.0, Swashbuckle will generate Schema's (descriptions of the data types exposed by an API) based on the behavior of the Newtonsoft serializer. This made sense because that was the serializer that shipped with ASP.NET Core at the time. However, since version 3.0.0, ASP.NET Core introduces a new serializer System.Text.Json (STJ) out-of-the-box, and if you want to continue using Newtonsoft, you need to install a separate package and explicitly opt-in. From Swashbuckle 5.0.0 and beyond a similar pattern is used. That is, out-of-the-box Swashbuckle will assume you're using the STJ serializer and generate Schema's based on its behavior. If you're using Newtonsoft, then you'll need to install a separate Swashbuckle package and explicitly opt-in. This is a required step, regardless of which version of ASP.NET Core you're using.
In summary ...
If you're using System.Text.Json (STJ), then the setup described above will be sufficient, and STJ options/attributes will be automatically honored by the Swagger generator.
If you're using Newtonsoft, then you'll need to install a separate package and explicitly opt-in to ensure that Newtonsoft settings/attributes are automatically honored by the Swagger generator:
Package Manager : Install-Package Swashbuckle.AspNetCore.Newtonsoft
CLI : dotnet add package Swashbuckle.AspNetCore.Newtonsoft
services.AddMvc();
services.AddSwaggerGen(c =>
{
c.SwaggerDoc("v1", new OpenApiInfo { Title = "My API", Version = "v1" });
});
services.AddSwaggerGenNewtonsoftSupport(); // explicit opt-in - needs to be placed after AddSwaggerGen()Swashbuckle relies heavily on ApiExplorer, the API metadata layer that ships with ASP.NET Core. If you're using the AddMvc helper to bootstrap the MVC stack, then ApiExplorer will be automatically registered and SB will work without issue. However, if you're using AddMvcCore for a more paired-down MVC stack, you'll need to explicitly add the ApiExplorer service:
services.AddMvcCore()
.AddApiExplorer();Additionally, if you are using conventional routing (as opposed to attribute routing), any controllers and the actions on those controllers that use conventional routing will not be represented in ApiExplorer, which means Swashbuckle won't be able to find those controllers and generate Swagger operations from them. For instance:
app.UseMvc(routes =>
{
// SwaggerGen won't find controllers that are routed via this technique.
routes.MapRoute("default", "{controller=Home}/{action=Index}/{id?}");
});You must use attribute routing for any controllers that you want represented in your Swagger document(s):
[Route("example")]
public class ExampleController : Controller
{
[HttpGet("")]
public IActionResult DoStuff() { /**/ }
}Refer to the routing documentation for more information.
Swashbuckle consists of multiple components that can be used together or individually depending on your needs. At its core, there's a Swagger generator, middleware to expose it as JSON endpoints, and a packaged version of the swagger-ui. These 3 packages can be installed with the Swashbuckle.AspNetCore "metapackage" and will work together seamlessly (see Getting Started) to provide beautiful API docs that are automatically generated from your code.
Additionally, there's add-on packages (CLI tools, an alternate UI etc.) that you can optionally install and configure as needed.
| Package | Description |
|---|---|
| Swashbuckle.AspNetCore.Swagger | Exposes Swagger JSON endpoints. It expects an implementation of ISwaggerProvider to be registered in the DI container, which it queries to retrieve OpenAPIDocument(s) that are then exposed as serialized JSON |
| Swashbuckle.AspNetCore.SwaggerGen | Injects an implementation of ISwaggerProvider that can be used by the above component. This particular implementation generates OpenApiDocument(s) from your routes, controllers and models |
| Swashbuckle.AspNetCore.SwaggerUI | Exposes an embedded version of the swagger-ui. You specify the API endpoints where it can obtain Swagger JSON, and it uses them to power interactive docs for your API |
| Package | Description |
|---|---|
| Swashbuckle.AspNetCore.Annotations | Includes a set of custom attributes that can be applied to controllers, actions and models to enrich the generated Swagger |
| Swashbuckle.AspNetCore.Cli | Provides a command line interface for retrieving Swagger directly from a startup assembly, and writing to file |
| Swashbuckle.AspNetCore.ReDoc | Exposes an embedded version of the Redoc UI (an alternative to swagger-ui) |
These packages are provided by the open-source community.
| Package | Description |
|---|---|
| Swashbuckle.AspNetCore.Filters | Some useful Swashbuckle filters which add additional documentation, e.g. request and response examples, authorization information, etc. See its Readme for more details |
| Unchase.Swashbuckle.AspNetCore.Extensions | Some useful extensions (filters), which add additional documentation, e.g. hide PathItems for unaccepted roles, fix enums for client code generation, etc. See its Readme for more details |
| MicroElements.Swashbuckle.FluentValidation | Use FluentValidation rules instead of ComponentModel attributes to augment generated Swagger Schemas |
| MMLib.SwaggerForOcelot | Aggregate documentations over microservices directly on Ocelot API Gateway |
The steps described above will get you up and running with minimal setup. However, Swashbuckle offers a lot of flexibility to customize as you see fit.
Check out the table below for the full list of options: