Swagger & Versioning

Articles

• Get started with Swashbuckle and ASP.NET Core ⭐
• OpenAPI support in minimal API apps ⭐
• Generate C# client for OpenAPI - NSwag ⭐⭐
• OpenAPI Specification on by default
• Open API support for ASP.NET Core Minimal API
• What is AddEndpointsApiExplorer in ASP.NET Core 6 - StackOverflow ⭐
• What is AddEndpointsApiExplorer in ASP.NET Core 6 ⭐
• OpenAPI vs. Swagger
• Multiple authorization scheme in Swagger UI in .NET core
• How to make ASP.NET Core API Documentation using Swagger and ReDoc (.NET 6)
• Understanding Swagger integration in .NET Core
• ASP.NET Core Versioning: MVC APIs ⭐
• ASP.NET Core Versioning: Minimal APIs ⭐
• API Versioning with ASP.NET Core 6.0 Minimal APIs
• Versioning ASP.NET Core MVC & Minimal APIs ⭐
• Issue: WithSummary and WithDescription deson't work in minimal api
• Issue: Using WithSummary() for Minimal API endpoints does not render when using Swashbuckle.AspNetCore
• Issue: Add support for WithSummary and WithDescription metadata
• Contract first OpenAPI development (but still use Swagger UI with ASP.NET Core)
• Generate C# client for OpenAPI
• NSwag.MSBuild ⭐
• NSwag Configuration Document ⭐
• Generating HTTP API clients using dotnet tools and Visual Studio Connected Services
• Generating HTTP API clients using Visual Studio Connected Services
• .NET OpenAPI tool command reference and installation
• Using OpenApiReference To Generate Open API Client Code ⭐⭐
• OpenApiReference Elements
• How to generate a swagger.json file on build in .NET core

Samples

• https://github.com/dotnet/aspnet-api-versioning/tree/main/examples/AspNetCore/WebApi ⭐⭐
• https://github.com/joaofbantunes/MinimalVersionedOpenApiSample
• joaofbantunes/SwaggerUiWithoutGenSample
• https://github.com/kaylumah/GenerateCSharpClientForOpenAPI

Notes

• adding custom description to response status code possible with WithOpenApi() method Issue registered here:

endpoints.MapPost("/", CreateProducts)
.WithOpenApi(operation => new(operation)
{
	Summary = "Creating a New Product",
        Description = "Creating a New Product",
        operation.Responses[StatusCodes.Status401Unauthorized].Description = "UnAuthorized request.";
        operation.Responses[StatusCodes.Status400BadRequest].Description = "Invalid input for creating product.";
})
.RequireAuthorization()
 .Produces<CreateProductResponse>(StatusCodes.Status201Created)
 .Produces<StatusCodeProblemDetails>(StatusCodes.Status401Unauthorized)
 .Produces<StatusCodeProblemDetails>(StatusCodes.Status400BadRequest)
.WithName("CreateProduct")
.WithDisplayName("Create a new product.");

Swashbuckle.AspNetCore.Annotations package also support this functionality with following code:

 endpoints.MapPost("/", CreateProducts)
.WithOpenApi(operation => new(operation)
{
	Summary = "Creating a New Product", Description = "Creating a New Product"
})
.RequireAuthorization()
.WithName("CreateProduct")
.WithDisplayName("Create a new product.")
.WithMetadata(new SwaggerResponseAttribute(
	StatusCodes.Status401Unauthorized,
	"UnAuthorized request.",
	typeof(StatusCodeProblemDetails)))
.WithMetadata(new SwaggerResponseAttribute(
	StatusCodes.Status400BadRequest,
	"Invalid input for creating product.",
	typeof(StatusCodeProblemDetails)))
.WithMetadata(
	new SwaggerResponseAttribute(
		StatusCodes.Status201Created,
		"Product created successfully.",
		typeof(CreateProductResponse)));