Objective : We have versioned our Web APi and want to create swagger /OpenAPI documentation version specific. i.e. when user will select specific version he would be able to see api specific to selected version.
Versioning for API is easy using ASP.NET core's inbuilt middle ware. I have created a separate post related to API versioning. This post is specific to creation of version specific swagger document.
Nuget Packages : below are the list of Nuget packages needed to implement versioning and Swagger documentation in the application.
Microsoft.AspNetCore.Mvc.Version : To implement versioning.
Microsoft.AspNetCore.Mvc.Versioning.ApiExplorer: Used by swagger to generate version specific document.
Swashbuckle.AspNetCore.Swagger : Swagger middleware exposes json endpoint.
Swashbuckle.AspNetCore.SwaggerGen : Generates JSON file
Swashbuckle.AspNetCore.SwaggerUI : Generates interactive UI documentation for API.
Now, we will see code which we have to add in ConfigureServices and Configure methods:
Need to add below services to implement inbuilt versioning functionality:
services.AddApiVersioning(o =>
{
o.AssumeDefaultVersionWhenUnspecified = true;
o.DefaultApiVersion = new ApiVersion(1, 0);
}); // inbuilt versioning implementation
services.AddVersionedApiExplorer(); // swagger versioning specific
// above code is required to implement versioning. below code is required for swagger documentation.
services.AddSwaggerGen(
options =>
{
var provider = services.BuildServiceProvider().GetRequiredService<IApiVersionDescriptionProvider>();
// add a swagger document for each discovered API version
foreach (var description in provider.ApiVersionDescriptions)
{
options.SwaggerDoc(description.GroupName, new OpenApiInfo { Version = description.ApiVersion.ToString(),
Description ="Sample API version: "+ description.GroupName ,
Title="API Versioning Sample"
});
}
var xmlFile = $"{Assembly.GetExecutingAssembly().GetName().Name}.xml";
var xmlPath = Path.Combine(AppContext.BaseDirectory, xmlFile);
Console.WriteLine("***************************** " + xmlPath);
options.IncludeXmlComments(xmlPath);
});
We need to add below code in Configure method to enable swagger documentation :
app.UseSwagger();
app.UseSwaggerUI(
options =>
{
var provider = app.ApplicationServices.GetRequiredService<IApiVersionDescriptionProvider>();
foreach (var description in provider.ApiVersionDescriptions)
{
options.SwaggerEndpoint( $"/swagger/{description.GroupName}/swagger.json",description.GroupName.ToUpperInvariant());
}
});
Now we have to add APIVersion Attribute on Controller /Action methods. like :
/// <summary>
/// this is sample api for version 1.0
/// </summary>
[ApiVersion("1.0")]
[ApiController]
[Route("api/v{version:apiVersion}/[controller]")]
public class EmployeeController : ControllerBase
{
/// <summary>
/// Get api for version 1.0
/// </summary>
[HttpGet]
public IActionResult Get()
{
return Ok(" Hello from v1");
}
}
/// <summary>
/// this is sample api for version 2.0
/// </summary>
[ApiVersion("2.0")]
[ApiController]
[Route("api/v{version:apiVersion}/[controller]")]
public class Employee2Controller : ControllerBase
{ /// <summary>
/// Get api for version 2.0
/// </summary>
///
[HttpGet]
public IActionResult Get()
{
return Ok(" Hello from v2");
}
}
[Copy paste above code in editor for better readability/understanding]
Some important point to remember:
1. Make sure that each action method is decorated with proper get/post attribute.
2. Route is specified for each action method.
3. Xml comments are added for each action method.
4. Go to project Properties->build->check-Xml document file. ( if you are using xml comments in swagger)
Resource :
https://github.com/domaindrivendev/Swashbuckle.AspNetCore/blob/master/README.md#list-multiple-swagger-documents
