Add OpenAPI Swagger API Versioning – Guidelines
Today in this article, We shall see how to enable Swagger API Versioning i.e OpenAPI versioning to the API documentation in ASP.NET Core. For .Net core API versioning, Swagger or Swashbuckle Nuget package, let you add required support for API Versioning supporting Swagger V2.0 or OpenAPI V3.0 specifications.
In our last article on API versioning, we learned a few best practices,
ASP.NET Core uses OpenAPI V3.0 specifications which are guidelines and specifications around how the API documentation should be.
In today’s article, we shall cover below,
Create ASP.NET Core API
Create ASP.NET Core 3.1 or .NET 5.0 API
Add Swashbuckle.AspNetCore NuGet package
Please add the below Nuget package to your API using a Command prompt or PMC(package manager console) or Nuget Package Manager
PM> Install-Package Swashbuckle.AspNetCore -Version 5.6.3
Note: Please update the version to the latest available.
This NuGet package shall add all other required components as shown below and you need not have to add them explicitly,
- Swashbuckle.AspNetCore.SwaggerUI
- Swashbuckle.AspNetCore.Swagger
- Swashbuckle.AspNetCore.SwaggerGen
Note: for .NET 5 and above project template will add the above Nuget package by default.
Add Versioning Nuget package
Please add below the Nuget package for versioning support.
PM> Install-Package Microsoft.AspNetCore.Mvc.Versioning -Version 4.2.0
The above Nuget package will enable versioning support to the API.
Add Versioning ApiExplorer Nuget package
Please add below the ApiExplorer Nuget package
PM> Install-Package Microsoft.AspNetCore.Mvc.Versioning.ApiExplorer -Version 4.2.0
This NuGet package will be used for discovering metadata such as the list of API-versioned controllers and actions, their URLs, and allowed HTTP methods.
Update ConfigureServices() method as below,
Please add API versioning to the service collection by adding below AddApiVersioning() to the ConfigureServices() method as shown below,
Define Swagger versioning format
Please add API versioning explorer to the service collection by adding below AddVersionedApiExplorer() to the ConfigureServices() method as shown below,
Above we are defining the GroupNameFormat convention to be used to create group names from API version
Let’s define SwaggerDoc using API Version Descriptor by discovering metadata such as the list of API-versioned controllers and actions.
OpenApiInfo class properties are defined as below. Below defined Title , Version and Description can be defined and customized perversion as needed.
private OpenApiInfo CreateMetaInfoAPIVersion(ApiVersionDescription apiDescription)
{
return new OpenApiInfo
{
Title = "MyTestService",
Version = apiDescription.ApiVersion.ToString(),
Description = " This service is TEST sample service which provides ability to get weather control data ",
};
}
Update Configure() method
Add below line UseSwagger and UseSwaggerUI to Configure() method enabling API pipeline with Swagger capability as shown below,
app.UseSwagger(c =>
{
c.RouteTemplate = "/swagger/{documentName}/swagger.json";
});
UseSwaggerUI
app.UseSwaggerUI(c =>
{
foreach (ApiVersionDescription description in provider.ApiVersionDescriptions)
{
c.SwaggerEndpoint($"/swagger/{description.GroupName}/swagger.json", description.GroupName.ToUpperInvariant());
}
});
provider instance can be injected using IApiVersionDescriptionProvider using Configure method as below,
public void Configure(IApplicationBuilder app, IWebHostEnvironment env,IApiVersionDescriptionProvider provider) { }
Let’s execute the swagger URL. You shall see all available versions will be listed below.
Let’s select version V1 and verify the definition generated. Swagger will show only the selected API version definition as below.
V1-API Version
V2-API Version
References :
Do you have any comments or ideas or any better suggestions to share?
Please sound off your comments below.
Happy Coding !!
Please bookmark this page and share it with your friends. Please Subscribe to the blog to receive notifications on freshly published(2024) best practices and guidelines for software design and development.
How are you accessing provider in app.UseSwaggerUI call?
Hello Zam , Thanks for your query.
Please DI IApiVersionDescriptionProvider in the configure method. I have updated the details. Thanks