Swashbuckle adds OpenAPI document generation to an ASP.NET Core API. It reads endpoint information from ASP.NET Core metadata services, builds a machine-readable description, and provides middleware to serve it. Optional Swagger UI middleware lets you explore and test the API in a browser. OpenAPI is the specification; Swagger names the related tooling and Swashbuckle methods. section 11.1
To add it to a minimal API:
- Install the Swashbuckle.AspNetCore NuGet package, then register AddEndpointsApiExplorer() and AddSwaggerGen() before building the app. section 11.1
- Call UseSwagger() to serve the document, by default at /swagger/v1/swagger.json. Call UseSwaggerUI() to make the browser interface available at /swagger. section 11.1 section 11.7
- Open /swagger to inspect endpoints, request and response schemas, and documented responses. Choose Try it out to enter parameters and send a request. section 11.2
A small fruit API
A minimal API with GET and POST fruit endpoints can register the two services and both middleware components. Swagger UI then displays those endpoints and can send requests to them. Check its response descriptions against real responses: a GET that returns 404 may initially be documented only as returning 200. Add endpoint metadata when the generated description leaves out important behavior. section 11.1 section 11.2 section 11.7
WebApplicationBuilder builder = WebApplication.CreateBuilder(args);
if(builder.Environment.IsDevelopment())
{
builder.Services.AddEndpointsApiExplorer();
builder.Services.AddSwaggerGen();
}
WebApplication app = builder.Build();
if(app.Environment.IsDevelopment())
{
app.UseSwagger();
app.UseSwaggerUI();
}
app.Run();
This setup registers and enables Swashbuckle only in development when Swagger UI is needed for local testing. section 11.5.3
Descriptions can be refined with endpoint metadata or XML documentation comments. For XML comments, enable documentation-file generation, configure IncludeXmlComments(), and use a static or instance method handler; in .NET 7, this approach does not support lambda handlers or local functions. For a protected API, define a security scheme and declare its requirements so Swagger UI can attach a token to test requests. Swashbuckle and other OpenAPI tools may adopt specification features at different speeds, so check the generated document when relying on newer features. section 11.5.3 section 25.5 section 11.6.3
