Documentation

Nomirun Host HTTP API Versioning

API Versioning

API versioning maintains compatibility as software evolves. It allows existing applications to use older API versions while new versions introduce improvements. This structured approach helps manage changes, communicate updates clearly, prevent unexpected failures, and enable gradual deprecation of outdated versions—balancing stability with innovation.

Nomirun Host supports API versioning out of the box. When you generate a new Nomirun module, you get this Swagger documentation extension code example:

using Asp.Versioning.ApiExplorer;
using Microsoft.Extensions.DependencyInjection;
using Microsoft.OpenApi.Models;

namespace ShoppingModule.Extensions;

 public static class SwaggerDocumentationExtensions
 {
     public static void ConfigureSwaggerDocs(this IServiceCollection services)
     {
         services.AddSwaggerGen(options =>
         {
             // Add other Swagger options.
             options.IncludeApiXmlDocumentation(nameof(ShoppingModule));
         });
     }
 }

The above gives you full control over the module swagger documentation. You can add authentication required for your API, or you can add XML documentation and annotations by uncommenting some code above.

For API versioning, you do not need to do anything.

All you need to do, is to add [ApiVersion] attribute to your controller or controller actions like:

[Route("api")]
[ApiVersion(2.0)]
public class UserAddressController : NomirunApiController
{
...
}

When you run your module, you’ll get 2 different versions in the Swagger UI.

Swagger UI versioning

Note that the default version is v1 and that is used automatically.

2025 Nomirun©