How to configure Swagger for a version enabled .NET Core API?

Once we start adding multiple versions to our .NET Core API, it becomes difficult to visualize the differences between versions. Can Swagger be configured to work with multiple versions of our API?

Yes, with right configuration, Swagger can help us. Let us see how this can be achieved.

Though lot of examples available for this solution, there are significant improvements done by Swashbuckle team to move to Open API Specification version 3.0.1 (also called OAS3). My aim is to simplify Swagger configuration with a working example.

Here is the GitHub Repo for code enthusiasts.

https://github.com/suryasreepada/APIVersionsWithSwagger

Tools and Environment

• Visual Studio 2019 Community
• Windows 10 Pro
• .NET Core 3.1

Nuget Packages used

• Microsoft.AspNetCore.Mvc.Versioning v4.1.1
• Microsoft.AspNetCore.Mvc.Versioning.ApiExplorer v4.1.1
• Swashbuckle.AspNetCore.Swagger v5.5.1
• Swashbuckle.AspNetCore.SwaggerUI v5.5.1
• Swashbuckle.AspNetCore.SwaggerGen v5.5.1
• Swashbuckle.AspNetCore.Annotations v5.5.1

Let us dive into the details

How does my Startup.cs looks like? To keep this code simple, I have used extension methods to do the ground work.

Note: It is highly recommended to move these extension methods to a Nuget package (hopefully to a private Nuget Repository) for organization wide usage to keep this configuration consistent across all APIs.

Startup.cs

I am using a PathBase option in Configure method.

There is greater cause for utilizing PathBase option in .NET Core API.

I have explained that in separate blog. Here is the link.

Here is the implementation for UseCustomPrefix method

UseCustomPrefix method implementation

API Versioning Configuration:

Let us see the steps for configuring API Version support. We just need to enable version reporting and set group name format.

AddApiVersioningSupport extension method implementation

Attributes used for routing and specifying HTTP Action versions in controller class. Though the rote (GetUser) is same for both actions, it’s behavior changes based on the version requested. This is specified using [MapToApiVersion] attribute.

SampleController.cs

Swagger Configuration:

There are two parts to completely configure Swagger in Startup class.

1. ConfigureServices method to configure and customize Swagger Page generation (Header part of the page). This can be achieved by adding SwaggerDoc support for each API Version.

AddSwaggerGenSupport extension method implementation

2. Configure method to configure and customize Swagger UI (HTTP Actions available for an API).

This can be achieved by adding Swagger UI support for each API Version to generate HTTP Actions into respective OAS3 JSON format.

UseCustomSwaggerUI extension method implementation

Now run the application and see what we can observe on Swagger UI.

Header section displays Company, Contact and other information.

On top right, we can see multiple API Definitions in dropdown.

Swagger Page Header Part

When GET method in Sample controller is expanded, we can see the response with name and userId fields if v1 API Definition is selected.

HTTP Actions for version v1

If v2 API Definition is selected, then we can see the response with name, userId and startDate fields.

HTTP Actions for version v2

You can test this functionality by providing appropriate version number (1.0 or 1 for short form and 2.0 or 2 for short form) and see the difference in response. Click on “Try it out” button and compare responses for each version.

Conclusion

With right configuration, we can have Swagger support for version enabled .NET Core API.

Please share your questions and comments.