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,

• RESTFul API Versioning – 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 :

• RESTFul API Versioning – Best Practices

• Swagger API Documentation in .NET Core 3.1

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.