API Documentation

Adding documentation is often the final, pivotal step in making your versioned services available to clients and fosters their utilization. While there are many approaches to documenting your services, Swagger has quickly become the de facto method for describing REST services. The most popular way to provide Swagger documentation for REST services implemented ASP.NET is using Swashbuckle.

The ASP.NET API versioning project provides several new API explorer implementations that make it easy to add versioning into your Swagger and Swashbuckle configurations. Each of these API explorers do all of the heavy lifting to discover and collate your REST services by API version. They do not directly rely on nor use Swagger or Swashbuckle so that you can use them for other scenarios as well.

ASP.NET Web API

Everything you need to add versioned documentation to your ApiController services.

config.AddApiVersioning();

// format the version as "'v'major[.minor][-status]"
var apiExplorer = config.AddVersionedApiExplorer( o => o.GroupNameFormat = "'v'VVV" );

config.EnableSwagger(
    "{apiVersion}/swagger",
    swagger =>
    {
        swagger.MultipleApiVersions(
            ( apiDescription, version ) => apiDescription.GetGroupName() == version,
            info =>
            {
                foreach ( var group in apiExplorer.ApiDescriptions )
                {
                    info.Version( group.Name, $"Sample API {group.ApiVersion}" );
                }
            } );
    } )
 .EnableSwaggerUi( swagger => swagger.EnableDiscoveryUrlSelector() );

Review the sample project for additional setup and configuration options.

ASP.NET Web API with OData

Everything you need to add versioned documentation to your ODataController services.

configuration.AddApiVersioning();

var modelBuilder = new VersionedODataModelBuilder( configuration )
{
    ModelConfigurations = { new MyModelConfiguration() }
};
var models = modelBuilder.GetEdmModels();

configuration.MapVersionedODataRoutes( "odata", "api", models );

// format the version as "'v'major[.minor][-status]"
var apiExplorer = configuration.AddODataApiExplorer( o => o.GroupNameFormat = "'v'VVV" );

configuration.EnableSwagger(
    "{apiVersion}/swagger",
    swagger =>
    {
        swagger.MultipleApiVersions(
            ( apiDescription, version ) => apiDescription.GetGroupName() == version,
            info =>
            {
                foreach ( var group in apiExplorer.ApiDescriptions )
                {
                    info.Version( group.Name, $"Sample API {group.ApiVersion}" );
                }
            } );
    } )
 .EnableSwaggerUi( swagger => swagger.EnableDiscoveryUrlSelector() );

Review the sample project for additional setup and configuration options.

Note: This API explorer does not directly tie into the Swashbuckle with OData support because that project also prescribes how API versioning is performed, which is incompatible with this project. This may change or improve in the future.

ASP.NET Core

Everything you need to add versioned documentation to your ControllerBase services.

Prior to 3.0, the setup was:
services.AddMvcCore().AddApiExplorer().AddVersionedApiExplorer( options => { /* config */ } );

public class ConfigureSwaggerOptions : IConfigureOptions<SwaggerGenOptions>
{
  readonly IApiVersionDescriptionProvider provider;

  public ConfigureSwaggerOptions( IApiVersionDescriptionProvider provider ) =>
    this.provider = provider;

  public void Configure( SwaggerGenOptions options )
  {
    foreach ( var description in provider.ApiVersionDescriptions )
    {
      options.SwaggerDoc(
        description.GroupName,
          new OpenApiInfo()
          {
            Title = $"Sample API {description.ApiVersion}",
            Version = description.ApiVersion.ToString(),
          } );
    }
  }
}

public void ConfigureServices( IServiceCollection services )
{
  // format the version as "'v'major[.minor][-status]"
  services.AddMvc();
  services.AddApiVersioning();
  services.AddVersionedApiExplorer( options => options.GroupNameFormat = "'v'VVV" );
  services.AddTransient<IConfigureOptions<SwaggerGenOptions>, ConfigureSwaggerOptions>();
  services.AddSwaggerGen();
}

public void Configure( IApplicationBuilder app, IApiVersionDescriptionProvider provider )
{
    app.UseMvc();
    app.UseSwagger();
    app.UseSwaggerUI(
        options =>
        {
            foreach ( var description in provider.ApiVersionDescriptions )
            {
                options.SwaggerEndpoint(
                    $"/swagger/{description.GroupName}/swagger.json",
                    description.GroupName.ToUpperInvariant() );
            }
        } );
}

Review the sample project for additional setup and configuration options.

ASP.NET Core with OData

Everything you need to add versioned documentation to your ODataController services.

public class ConfigureSwaggerOptions : IConfigureOptions<SwaggerGenOptions>
{
  readonly IApiVersionDescriptionProvider provider;

  public ConfigureSwaggerOptions( IApiVersionDescriptionProvider provider ) =>
    this.provider = provider;

  public void Configure( SwaggerGenOptions options )
  {
    foreach ( var description in provider.ApiVersionDescriptions )
    {
      options.SwaggerDoc(
        description.GroupName,
          new Info()
          {
            Title = $"Sample API {description.ApiVersion}",
            Version = description.ApiVersion.ToString(),
          } );
    }
  }
}

public void ConfigureServices( IServiceCollection services )
{
  // format the version as "'v'major[.minor][-status]"
  services.AddMvc( options => options.EnableEndpointRouting = false );
  services.AddApiVersioning();
  services.AddOData().EnableApiVersioning();
  services.AddVersionedApiExplorer( options => options.GroupNameFormat = "'v'VVV" );
  services.AddTransient<IConfigureOptions<SwaggerGenOptions>, ConfigureSwaggerOptions>();
  services.AddSwaggerGen();
}

public void Configure(
    IApplicationBuilder app,
    VersionedODataModelBuilder modelBuilder,
    IApiVersionDescriptionProvider provider )
{
    var models = modelBuilder.GetEdmModels();
    app.UseMvc( routes => routes.MapVersionedODataRoutes( "odata", null, models ) );
    app.UseSwagger();
    app.UseSwaggerUI(
        options =>
        {
            foreach ( var description in provider.ApiVersionDescriptions )
            {
                options.SwaggerEndpoint(
                    $"/swagger/{description.GroupName}/swagger.json",
                    description.GroupName.ToUpperInvariant() );
            }
        } );
}

Review the sample project for additional setup and configuration options.