domaindrivendev/Swashbuckle.AspNetCore is a open-source project on GitHub, written primarily in C#. It has 5.5k stars. Swagger tools for documenting API's built on ASP.NET Core
Snapshot summary built from the project's own GitHub metadata — there's no written TopGit review yet. The page will update automatically when a full review is published.
WHY NO REVIEW YET
TopGit writes full reviews for the most-starred, most-requested repositories. This page is a snapshot until then — see the READ ME tab for the original README in full.
OpenAPI (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/3.1/3.2 generator, Swashbuckle.AspNetCore also provides
an embedded version of the awesome swagger-ui project that's powered by the generated OpenAPI 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 OpenAPI document, you've opened the treasure chest of OpenAPI-based
tools including a client generator that can be targeted to a wide range of popular platforms. See swagger-codegen
for more details.
[!IMPORTANT]
Version 11.0 of Swashbuckle.AspNetCore introduces breaking changes due to dropping support for .NET 8 and .NET 9, upgrading our dependency on
Microsoft.OpenApi to version 3.x.x to add support for generating OpenAPI 3.2 documents, and upgrading the embedded
Redoc UI to version 3.x. Please see Migrating to Swashbuckle.AspNetCore v11 for more details.
Version 10.0 of Swashbuckle.AspNetCore introduced breaking changes due to upgrading our dependency on Microsoft.OpenApi
to version 2.x.x to add support for generating OpenAPI 3.1 documents. Please see Migrating to Swashbuckle.AspNetCore v10 for more details.
Compatibility
Swashbuckle Version
ASP.NET Core
OpenAPI/Swagger Versions
Microsoft.OpenApi
swagger-ui
Redoc
>= 10.0.0
3.2, 3.1, 3.0, 2.0
>= 10.0.0
3.2, 3.1, 3.0, 2.0
10.0.x, 9.0.x, 8.0.x
3.1, 3.0, 2.0
9.0.x, 8.0.x
3.0, 2.0
Getting Started
First install the kitchen-sink NuGet package into your ASP.NET Core application:
dotnet add package Swashbuckle.AspNetCore
Next, register the OpenAPI (Swagger) generator in your application's startup path, defining one or more OpenAPI documents. For example:
using Microsoft.OpenApi;
var builder = WebApplication.CreateBuilder(args);
builder.Services.AddMvc();
builder.Services.AddSwaggerGen(options =>
{
options.SwaggerDoc("v1", new OpenApiInfo { Title = "My API", Version = "v1" });
});
var app = builder.Build();
app.UseSwagger();
app.Run();
snippet source | anchor
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
return [];
}
snippet source | anchor
[!NOTE]
If you omit the explicit parameter bindings, the generator will describe them as "query" parameters by default.
Then, expose the OpenAPI JSON document endpoint(s) using one of following methods:
Add endpoints if you're using endpoint-based routing:
// Your own endpoints go here, and then...
app.MapSwagger();
snippet source | anchor
Adding the OpenAPI middleware:
app.UseSwagger();
snippet source | anchor
At this point, you can launch your application and view the generated OpenAPI document at /swagger/v1/swagger.json.
Finally, you can optionally add the swagger-ui middleware to expose interactive documentation, specifying the OpenAPI document(s) to power it from:
app.UseSwaggerUI(options =>
{
options.SwaggerEndpoint("v1/swagger.json", "My API V1");
});
snippet source | anchor
Now you can restart your application and view 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.AspNetCore 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 must install a separate package and explicitly opt-in. By default Swashbuckle.AspNetCore will assume
that 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.AspNetCore package, Swashbuckle.AspNetCore.Newtonsoft to explicitly opt-in.
Below is an example of how to do this for ASP.NET Core MVC:
services.AddMvc();
services.AddSwaggerGen(options =>
{
options.SwaggerDoc("v1", new OpenApiInfo { Title = "My API", Version = "v1" });
});
services.AddSwaggerGenNewtonsoftSupport();
snippet source | anchor
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.AspNetCore should 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();
snippet source | anchor
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 OpenAPI operations for 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?}");
});
snippet source | anchor
You must use attribute routing for any controllers that you want represented in your OpenAPI document(s):
[Route("example")]
public class ExampleController : Controller
{
[HttpGet("")]
public IActionResult DoStuff()
{
// Your implementation
return Empty;
}
}
snippet source | anchor
Refer to the ASP.NET Core MVC routing documentation for more information.
Components
Swashbuckle.AspNetCore consists of multiple components that can be used together or individually depending on your needs.
At its core, there's an OpenAPI generator, middleware to expose OpenAPI (Swagger) 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 (see Getting Started) to provide API documentation that is automatically generated from your code.
Additionally, there are add-on packages (CLI tools, an alternate UI using Redoc etc.) that you can install and configure as needed.
"Core" Packages
Package
NuGet
Description
Swashbuckle.AspNetCore.Swagger
Exposes OpenAPI 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 OpenAPI 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).
[!NOTE]
Swashbuckle.AspNetCore.ReDoc embeds Redoc 3, which collects anonymous usage telemetry by default.
To turn it off, set the disableTelemetry option when configuring the middleware:
These packages are provided by the .NET open-source community.
Package
NuGet
Description
Swashbuckle.AspNetCore.Filters
Some useful Swashbuckle.AspNetCore 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 OpenAPI 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.AspNetCore offers a lot of flexibility to customize as you see fit.
Check out the table below for the full list of possible configuration options.
Component
Configuration and Customization
Swashbuckle.AspNetCore.Swagger
Change the Path for OpenAPI JSON Endpoints
Modify OpenAPI with Request Context
Serialize OpenAPI JSON in the 3.1 format
Serialize OpenAPI JSON in the 3.2 format
Serialize Swagger JSON in the 2.0 format
Working with Virtual Directories and Reverse Proxies
Customizing how the OpenAPI document is serialized
Swashbuckle.AspNetCore.SwaggerGen
Assign Explicit OperationIds
List Operations Responses
Flag Required Parameters and Schema Properties
Handle Forms and File Uploads
Handle File Downloads
Include Descriptions from XML Comments
Provide Global API Metadata
Generate Multiple OpenAPI Documents
Omit Obsolete Operations and/or Schema Properties
Omit Arbitrary Operations
Customize Operation Tags (e.g. for UI Grouping)
Change Operation Sort Order (e.g. for UI Sorting)
Customize Schema Ids
Override Schema for Specific Types
Extend Generator with Operation, Schema & Document Filters
Add Security Definitions and Requirements
Add Security Definitions and Requirements for Bearer auth
How active is development on domaindrivendev/Swashbuckle.AspNetCore?
The most recent commit recorded on domaindrivendev/Swashbuckle.AspNetCore was 5 days ago, based on the GitHub push timestamp. The repository has 1.3k forks — one of the better signals of community interest.
How many stars does domaindrivendev/Swashbuckle.AspNetCore have?
domaindrivendev/Swashbuckle.AspNetCore has 5.5k GitHub stars — refresh the page for the live number, or check github.com/domaindrivendev/Swashbuckle.AspNetCore. TopGit mirrors GitHub's count but does not claim minute-by-minute accuracy.
Is domaindrivendev/Swashbuckle.AspNetCore open source?
Yes — domaindrivendev/Swashbuckle.AspNetCore ships under the MIT license, which makes its source code freely readable (and, depending on license terms, forkable and reusable). Source: github.com/domaindrivendev/Swashbuckle.AspNetCore.
What is domaindrivendev/Swashbuckle.AspNetCore?
domaindrivendev/Swashbuckle.AspNetCore (domaindrivendev/Swashbuckle.AspNetCore) is a C# project on GitHub. From the project's own README: Swagger tools for documenting API's built on ASP.NET Core
Where do I read more about domaindrivendev/Swashbuckle.AspNetCore?
This TopGit page is a snapshot — the READ ME tab shows the project's own README content (links stripped, images preserved). The GitHub repository at github.com/domaindrivendev/Swashbuckle.AspNetCore is the definitive source.
Read full README in the tab above.
Curious whether Swashbuckle.AspNetCore is right for you?
Let ChatGPT, Claude, or Perplexity look into it — click below and see what AI actually says about Swashbuckle.AspNetCore.