Swashbuckle is a set of ASP.NET Core services, middleware, and tools for documenting a web API with OpenAPI. It generates a machine-readable swagger.json description of available endpoints and provides SwaggerUI, a browser-based view that can also be used to test them. This gives developers a way to discover an API even though the API itself has no conventional user interface. section 3.5 section 11.2.1
In an ASP.NET Core web API created with Visual Studio’s Enable OpenAPI support option, the Swashbuckle setup is already present. The generator service creates the description; one middleware exposes its JSON endpoint, and another serves SwaggerUI. The shown middleware runs only in the Development environment. section 3.2.2
// ...
builder.Services.AddSwaggerGen(); #1
// ...
if (app.Environment.IsDevelopment())
{
app.UseSwagger(); #2
app.UseSwaggerUI(); #3
}
In Program.cs, AddSwaggerGen registers generation, while UseSwagger and UseSwaggerUI expose the generated document and its browser interface during development. section 3.2.2
To check the result in the board-game API:
- Run the application in Debug mode and open /swagger/v1/swagger.json to inspect the generated OpenAPI description. section 3.2.2
- Open /swagger to browse the same documentation in SwaggerUI and inspect the endpoints and return types. section 3.2.2
The defaults are a starting point: the generator uses OpenAPI 3.0 and assumes API version 1.0. Service and middleware options can change settings such as the JSON endpoint. Swashbuckle can also refine generated documentation through data attributes and a filter pipeline, including descriptions of operations, parameters, and responses. section 3.2.2 section 11.5
Endpoint grouping shows why customization can matter. Swashbuckle automatically groups controller actions by controller name using OpenAPI tags. Minimal API endpoints lack that controller association and fall into a generic group; a SwaggerOperation attribute can assign related endpoints a more useful tag. section 11.2.7
app.MapGet("/auth/test/1",
[Authorize]
[EnableCors("AnyOrigin")]
[SwaggerOperation(
Tags = new[] { "Auth" }, #1
Summary = "Auth test #1 (authenticated users).",
Description = "Returns 200 - OK if called by " +
"an authenticated user regardless of its role(s).")]
The SwaggerOperation attribute assigns an Auth tag to an authorization-related Minimal API endpoint and supplies its summary and description. section 11.2.7
