rh072005 - SwashbuckleAspNetVersioningShim 2.2.1
Library to aid the combined use of Swashbuckle and ASP NET API Versioning
PM> Install-Package SwashbuckleAspNetVersioningShim -Version 2.2.1 -Source https://www.myget.org/F/rh072005/api/v3/index.json
> nuget.exe install SwashbuckleAspNetVersioningShim -Version 2.2.1 -Source https://www.myget.org/F/rh072005/api/v3/index.json
> dotnet add package SwashbuckleAspNetVersioningShim --version 2.2.1 --source https://www.myget.org/F/rh072005/api/v3/index.json
source https://www.myget.org/F/rh072005/api/v3/index.json
nuget SwashbuckleAspNetVersioningShim ~> 2.2.1
Copy to clipboard
> choco install SwashbuckleAspNetVersioningShim --version 2.2.1 --source https://www.myget.org/F/rh072005/api/v2
Import-Module PowerShellGet
Register-PSRepository -Name "rh072005" -SourceLocation "https://www.myget.org/F/rh072005/api/v2"
Install-Module -Name "SwashbuckleAspNetVersioningShim" -RequiredVersion "2.2.1" -Repository "rh072005"
Copy to clipboard
:warning: Future upgrades |
---|
Before using this library I would advise looking at this example first. If you still have a need for this library after this please add your comments to Issue #15. |
Update - My current plan is to archive this repository in November (2019) |
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
Getting started
- Start by creating a new ASP.NET Core Web Application
- Install the SwashbuckleAspNetVersioningShim NuGet package from
- Add the following code blocks to Startup.cs
using Microsoft.AspNetCore.Mvc.ApiExplorer;
using SwashbuckleAspNetVersioningShim;
public void ConfigureServices(IServiceCollection services)
{
services.AddMvc();
services.AddMvcCore().AddVersionedApiExplorer();
services.AddApiVersioning();
services.AddSwaggerGen(c => {
var provider = services.BuildServiceProvider().GetRequiredService<IApiVersionDescriptionProvider>();
c.ConfigureSwaggerVersions(provider);
});
...
//Note the change of method signature to include injection of IApiVersionDescriptionProvider
public void Configure(IApplicationBuilder app, IHostingEnvironment env, IApiVersionDescriptionProvider provider)
{
...
app.UseMvc();
app.UseSwagger(); app.UseSwaggerUI(c =>
{
c.ConfigureSwaggerVersions(provider);
});
...
}
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{api-version:apiVersion}/[controller]")]
public class ValuesController : Controller
{
// GET api/values
[HttpGet]
public IEnumerable<string> Get()
{
return new string[] { "value1", "value2" };
}
...
Configuring routes and templates
If you want to configure the titles on the Swagger description page you can pass a title template to ConfigureSwaggerVersions
inside ConfigureServices
in your Startup file.
public void ConfigureServices(IServiceCollection services)
{
services.AddMvc();
services.AddMvcCore().AddVersionedApiExplorer();
services.AddApiVersioning();
services.AddSwaggerGen(c => {
var provider = services.BuildServiceProvider().GetRequiredService<IApiVersionDescriptionProvider>();
c.ConfigureSwaggerVersions(provider, "Welcome to the documentation for version {0} of my API");
});
...
Similarly, if you want to change the text in the version drop down you can using the SwaggerVersionOptions
object. This lets you set the DescriptionTemplate
for the version selector and RouteTemplate
to alter the route.
//Note the change of method signature to include injection of IApiVersionDescriptionProvider
public void Configure(IApplicationBuilder app, IHostingEnvironment env, IApiVersionDescriptionProvider provider)
{
...
app.UseMvc();
app.UseSwagger();
app.UseSwaggerUI(c =>
{
c.ConfigureSwaggerVersions(provider, new SwaggerVersionOptions
{
DescriptionTemplate = "Vesion {0} docs", RouteTemplate = "/swagger/{0}/swagger.json"
});
});
...
}
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!";
}
Using querystring versions
As of version 1.0.0-beta.1 and thanks to Microsoft.AspNetCore.Mvc.Versioning, querystring versioned APIs are now supported.
In a controller where no API version is specified a new parameter will be added to Swagger and will default to the API version you are browsing.
So this controller
[ApiVersion("1.0")]
[Route("api/[controller]")]
public class ValuesController : Controller
{
// GET api/values
[HttpGet]
public IEnumerable<string> Get()
{
return new string[] { "value1", "value2" };
}
}
will look like this
License
See the LICENSE file for license rights and limitations (MIT).
-
Any 0.0
- Microsoft.AspNetCore.Mvc.Versioning.ApiExplorer (>= 2.2.0)
- Swashbuckle.AspNetCore (>= 3.0.0)
- .NETStandard 2.0: 2.0.0.0
Ownersrh072005 |
AuthorsRyan Hird |
Project URLhttps://github.com/rh072005/SwashbuckleAspNetVersioningShim |
LicenseUnknown |
TagsSwashbuckle ASP.NET Versioning Shim WebAPI Swagger AspNetCore MVC |
Info18 total downloads |
0 downloads for version 2.2.1 |
Download (6.47 KB) |
Found on the current feed only |
Package history
Version | Size | Last updated | Downloads | Mirrored? | |||
---|---|---|---|---|---|---|---|
2.2.1 | 6.47 KB | Thu, 19 Jul 2018 07:32:36 GMT | 0 | ||||
2.2.0 | 6.46 KB | Fri, 13 Jul 2018 14:54:05 GMT | 0 | ||||
2.1.0 | 6.43 KB | Mon, 19 Mar 2018 16:51:46 GMT | 1 | ||||
2.0.2 | 6.41 KB | Mon, 12 Feb 2018 10:18:34 GMT | 0 | ||||
2.0.1 | 6.46 KB | Tue, 26 Sep 2017 14:36:19 GMT | 1 | ||||
2.0.0 | 6.44 KB | Tue, 05 Sep 2017 12:41:12 GMT | 1 | ||||
2.0.0-beta1 | 6.46 KB | Wed, 23 Aug 2017 13:04:36 GMT | 1 | ||||
1.0.0 | 10.89 KB | Fri, 16 Jun 2017 16:08:02 GMT | 1 | ||||
1.0.0-beta4 | 10.9 KB | Wed, 17 May 2017 10:19:00 GMT | 0 | ||||
1.0.0-beta3 | 10.86 KB | Tue, 16 May 2017 16:16:35 GMT | 0 | ||||
1.0.0-beta2 | 9.69 KB | Mon, 15 May 2017 09:47:19 GMT | 3 | ||||
1.0.0-beta1 | 9.69 KB | Fri, 21 Apr 2017 15:03:21 GMT | 0 | ||||
0.5.0-pre | 11.57 KB | Thu, 13 Apr 2017 13:48:09 GMT | 1 | ||||
0.4.3-pre | 10.85 KB | Fri, 07 Apr 2017 09:32:48 GMT | 3 | ||||
0.4.2-pre | 10.79 KB | Fri, 10 Mar 2017 17:52:38 GMT | 1 | ||||
0.4.1-pre | 10.82 KB | Wed, 01 Mar 2017 16:37:46 GMT | 2 | ||||
0.4.0-pre | 10.82 KB | Wed, 01 Mar 2017 16:25:47 GMT | 1 | ||||
0.3.0-pre | 10.77 KB | Mon, 20 Feb 2017 16:23:04 GMT | 1 | ||||
0.2.2-pre | 10.77 KB | Thu, 09 Feb 2017 13:40:25 GMT | 0 | ||||
0.2.1-pre | 10.73 KB | Tue, 07 Feb 2017 11:28:04 GMT | 1 | ||||
0.2.0-pre | 10.55 KB | Thu, 02 Feb 2017 17:55:39 GMT | 0 | ||||
0.1.0-pre.1 | 10.5 KB | Fri, 03 Feb 2017 11:51:18 GMT | 0 |