dev

API Versioning in ASP.NET (Core) with Swagger & Swashbuckle & Swagger UI

Outline

In previous article I have sum up API versioning. In this post I want to show how it can be provided in WebAPI [1] via Swagger and Swashbuckle [2, 3].

Swashbuckle is a NuGet package for both .NET and .NETCore that enables to generate Swagger documentation for ASP.NET projects. It can generate a rich documentation from various sources – operations, operation attributes or documentation elements. Next,it can be extended via various customization (for more details, see Swashbuckle documentation and samples).

API Versioning via Swagger

In case of API versioning, it provides ways how to provide this task in a simple way via publishing of multiple specification documents. And subsequently if you want to describe some breaking changes between two versions, e.g., property UserName was changed to Name,  Swagger model enables to specify description property. This property is rendered as Implementation Notes paragraph in Swagger UI [4] (see Figure 1). If you want to define this property in WebAPI, you have to specify remarks element in XML documentation:

/// <summary>
/// Gets value object by specified identifier.
/// </summary>
/// <remarks>
/// Breaking Change. A new, enrich model is returned.
/// </remarks>
/// <param name="id">The identifier.</param>
/// <returns>Value object</returns>

This, all together, will provide following doc:

remarks
Figure 1. Generated Swagger documentation

Conclusion

When using Swagger via Swashbuckle, API versioning change documentation is a simple task that can be provides via definition of remarks element in the operation XML comment.

References

[1] https://github.com/aspnet

[2] https://github.com/domaindrivendev/Swashbuckle

[3] https://github.com/domaindrivendev/Swashbuckle.AspNetCore

[4] https://github.com/swagger-api/swagger-ui