bungeemonkee/swashbuckleaspnetversioningshim

Library to aid the combined use of Swashbuckle and ASP NET API Versioning

Swashbuckle ASP.NET Versioning Shim

This library aids the use of Swashbuckle and ASP NET Web API Versioning together and started from my attempt at resolving Swashbuckle.AspNetCore issue 244

Note: Development has been carried out with URL path versioning in mind. I've not tested it with the other versioning conventions that API versioning provide.

Getting started

• Start by creating a new ASP.NET Core Web Application
• Install the SwashbuckleAspNetVersioningShim NuGet package
  • Short term this will be a case of building from source
  • Mid term it will be hosted on MyGet Now available on MyGet
  • Long term it will be hosted on NuGet Now available on NuGet
• Add the following code blocks to Startup.cs

using SwashbuckleAspNetVersioningShim;
using Microsoft.AspNetCore.Mvc.ApplicationParts;

public void ConfigureServices(IServiceCollection services)
{
    // This replaces services.AddMvc(); because we need access to IMvcBuilder's ApplicationPartManager below
    var mvcBuilder = services.AddMvc();

    services.AddApiVersioning();
    services.AddSwaggerGen(c =>
    {
        SwaggerVersioner.ConfigureSwaggerGen(c, mvcBuilder.PartManager);
    });
    ...

//Note the change of method signature to include injection of ApplicationPartManager
public void Configure(IApplicationBuilder app, IHostingEnvironment env, ILoggerFactory loggerFactory, ApplicationPartManager partManager)
{
    ...
    app.UseSwagger();
    app.UseSwaggerUI(c =>
    {
        SwaggerVersioner.ConfigureSwaggerUI(c, partManager);
    });
    ...
}

All being well you can now continue to use ASP NET Web API Versioning as per it's documentation. As a minimum your web API controller will want an ApiVersionAttribute and a RouteAttribute. Using the default ValueController that's created with a new Web API project it would look like this

[ApiVersion("1.0")]
[Route("api/v{version:apiVersion}/[controller]")]
public class ValuesController : Controller
{
    // GET api/values
    [HttpGet]
    public IEnumerable<string> Get()
    {
        return new string[] { "value1", "value2" };
    }
    ...

Note about MapToApiVersion

When using MapToApiVersion (example here) methods will be added for each ApiVersionAttribute specified on the controller. In the example this results in Get() and GetV3() being added to the 2.0 and 3.0 Swagger document. To avoid this, which will cause an overload error in Swashbuckle, you will need to add explicitly add the MapToApiVersion attribute to both methods rather than letting Get() default.

Referring again to the example it would look like this

[ApiVersion("2.0")]
[ApiVersion("3.0")]
[Route("api/v{version:apiVersion}/helloworld")]
public class HelloWorld2Controller : Controller
{
    [HttpGet, MapToApiVersion("2.0")]
    public string Get() => "Hello world v2!";

    [HttpGet, MapToApiVersion("3.0")]
    public string GetV3() => "Hello world v3!";
}

License

See the LICENSE file for license rights and limitations (MIT).