Swashbuckle.AspNetCore

Swagger tooling for APIs built with ASP.NET Core.

Generate beautiful API documentation, including a UI to explore and test operations, directly from your application code.

In addition to its Swagger 2.0 and OpenAPI 3.0 generator, Swashbuckle also provides an embedded version of the awesome swagger-ui project that's powered by the generated Swagger JSON documents. 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.

But that's not all...

Once you have an API that can describe itself with a Swagger document, 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.

Compatibility

Getting Started

1. Install the kitchen-sink NuGet package into your ASP.NET Core application:

   dotnet add package Swashbuckle.AspNetCore
   

2. Register the Swagger generator in your application's startup path, defining one or more Swagger documents. For example:

   using Microsoft.OpenApi.Models;
   

   services.AddMvc();
   
   services.AddSwaggerGen(options =>
   {
       options.SwaggerDoc("v1", new OpenApiInfo { Title = "My API", Version = "v1" });
   });
   

3. Ensure your API endpoints and any parameters are decorated with [Http*] and [From*] attributes, where appropriate.

   [HttpPost]
   public void CreateProduct([FromBody] Product product)
   {
       // Implementation goes here
   }
   

   [HttpGet]
   public IEnumerable<Product> SearchProducts([FromQuery]string keywords)
   {
       // Implementation goes here
   }
   

   [!NOTE] If you omit the explicit parameter bindings, the generator will describe them as "query" parameters by default.

4. Expose the Swagger/OpenAPI JSON document endpoint(s) using one of following methods:

   • Add endpoints if you're using endpoint-based routing:

   app.MapEndpoints(endpoints =>
   {
       // Your own endpoints go here, and then...
       endpoints.MapSwagger();
   });
   

   • Inserting the Swagger/OpenAPI middleware:

   app.UseSwagger();
   

   At this point, you can spin up your application and view the generated Swagger document at /swagger/v1/swagger.json.

5. Optionally, insert the swagger-ui middleware if you want to expose interactive documentation, specifying the Swagger document(s) to power it from:

   app.UseSwaggerUI(options =>
   {
       options.SwaggerEndpoint("v1/swagger.json", "My API V1");
   });
   

   Now you can restart your application and check out the auto-generated, interactive documentation at /swagger.

System.Text.Json (STJ) vs Newtonsoft.Json (Json.NET)

In versions of Swashbuckle.AspNetCore prior to 5.0.0, Swashbuckle would generate Schemas (descriptions of the data types exposed by an API) based on the behavior of the Newtonsoft.Json serializer. This made sense because that was the serializer that shipped with ASP.NET Core at the time. However, since ASP.NET Core 3.0, ASP.NET Core introduces a new serializer, System.Text.Json (STJ) out-of-the-box.

If you want to use Newtonsoft.Json instead, you need to install a separate package and explicitly opt-in. By default Swashbuckle.AspNetCore will assume you're using the System.Text.Json serializer and generate Schemas based on its behavior. If you're using Newtonsoft.Json then you'll need to install a separate Swashbuckle package, Swashbuckle.AspNetCore.Newtonsoft to explicitly opt-in.

Below is an example of how to do this for ASP.NET Core MVC:

dotnet add package Swashbuckle.AspNetCore.Newtonsoft

services.AddMvc();

services.AddSwaggerGen(options =>
{
    options.SwaggerDoc("v1", new OpenApiInfo { Title = "My API", Version = "v1" });
});

services.AddSwaggerGenNewtonsoftSupport();

Swashbuckle, ApiExplorer, and Routing

Swashbuckle relies heavily on ApiExplorer, the API metadata layer that ships with ASP.NET Core. If you're using the AddMvc(...) helper methods to bootstrap the MVC stack, then API Explorer will be automatically registered and Swashbuckle will work without issue.

However, if you're using AddMvcCore(...) for a more paired-down MVC stack, you'll need to explicitly add the API Explorer services:

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 API Explorer, 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() { /* Your implementation */ }
}

Refer to the ASP.NET Core MVC routing documentation for more information.

Components

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 Swagger (OpenAPI) documentation as JSON endpoints, and a packaged version of the swagger-ui. These three packages can be installed with the Swashbuckle.AspNetCore "metapackage" and will work together seamlessly (see Getting Started) to provide beautiful API documentation that is automatically generated from your code.

Additionally, there's add-on packages (CLI tools, an alternate UI using Redoc etc.) that you can optionally install and configure as needed.

"Core" Packages

Package	NuGet	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 instance(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 instance(s) from your application endpoints (controllers, minimal endpoints etc.).
Swashbuckle.AspNetCore.SwaggerUI		Exposes an embedded version of swagger-ui. You specify the API endpoints where it can obtain Swagger documents from, and it uses them to power interactive documentation for your API.

Additional Packages

Package	NuGet	Description
Swashbuckle.AspNetCore.Annotations		Includes a set of custom attributes that can be applied to controllers/endpoints, actions and models to enrich the generated documentation.
Swashbuckle.AspNetCore.Cli		Provides a command line interface (CLI) for retrieving OpenAPI documents directly from an application start-up assembly and then writing to a file.
Swashbuckle.AspNetCore.ReDoc		Exposes an embedded version of the Redoc UI (an alternative to swagger-ui).

Community Packages

These packages are provided by the .NET open-source community.

Package	NuGet	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 enumerations 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.

Configuration and Customization

The steps described above will get you up and running with minimal set up. However, Swashbuckle offers a lot of flexibility to customize as you see fit.

Check out the table below for the full list of possible configuration options.