目前 Swashbuckle 和 Microsoft.AspNetCore.Mvc.Versioning 是朋友。它运作良好。我刚刚在 VS2017 中创建了测试项目并检查了它是如何工作的。
首先包含这两个nuget包：
<PackageReference Include="Microsoft.AspNetCore.Mvc.Versioning" Version="1.2.1" />
<PackageReference Include="Swashbuckle.AspNetCore" Version="1.0.0" />
在Startup.cs 中配置所有内容（阅读我的 cmets）：
public void ConfigureServices(IServiceCollection services)
{
services.AddMvc();
// Configure versions
services.AddApiVersioning(o =>
{
o.AssumeDefaultVersionWhenUnspecified = true;
o.DefaultApiVersion = new ApiVersion(1, 0);
});
// Configure swagger
services.AddSwaggerGen(options =>
{
// Specify two versions
options.SwaggerDoc("v1",
new Info()
{
Version = "v1",
Title = "v1 API",
Description = "v1 API Description",
TermsOfService = "Terms of usage v1"
});
options.SwaggerDoc("v2",
new Info()
{
Version = "v2",
Title = "v2 API",
Description = "v2 API Description",
TermsOfService = "Terms of usage v2"
});
// This call remove version from parameter, without it we will have version as parameter
// for all endpoints in swagger UI
options.OperationFilter<RemoveVersionFromParameter>();
// This make replacement of v{version:apiVersion} to real version of corresponding swagger doc.
options.DocumentFilter<ReplaceVersionWithExactValueInPath>();
// This on used to exclude endpoint mapped to not specified in swagger version.
// In this particular example we exclude 'GET /api/v2/Values/otherget/three' endpoint,
// because it was mapped to v3 with attribute: MapToApiVersion("3")
options.DocInclusionPredicate((version, desc) =>
{
var versions = desc.ControllerAttributes()
.OfType<ApiVersionAttribute>()
.SelectMany(attr => attr.Versions);
var maps = desc.ActionAttributes()
.OfType<MapToApiVersionAttribute>()
.SelectMany(attr => attr.Versions)
.ToArray();
return versions.Any(v => $"v{v.ToString()}" == version) && (maps.Length == 0 || maps.Any(v => $"v{v.ToString()}" == version));
});
});
}
public void Configure(IApplicationBuilder app, IHostingEnvironment env, ILoggerFactory loggerFactory)
{
loggerFactory.AddConsole(Configuration.GetSection("Logging"));
loggerFactory.AddDebug();
app.UseSwagger();
app.UseSwaggerUI(c =>
{
c.SwaggerEndpoint($"/swagger/v2/swagger.json", $"v2");
c.SwaggerEndpoint($"/swagger/v1/swagger.json", $"v1");
});
app.UseMvc();
}
有两个类可以解决问题：
public class RemoveVersionFromParameter : IOperationFilter
{
public void Apply(Operation operation, OperationFilterContext context)
{
var versionParameter = operation.Parameters.Single(p => p.Name == "version");
operation.Parameters.Remove(versionParameter);
}
}
public class ReplaceVersionWithExactValueInPath : IDocumentFilter
{
public void Apply(SwaggerDocument swaggerDoc, DocumentFilterContext context)
{
swaggerDoc.Paths = swaggerDoc.Paths
.ToDictionary(
path => path.Key.Replace("v{version}", swaggerDoc.Info.Version),
path => path.Value
);
}
}
RemoveVersionFromParameter 从 swagger UI 中删除了这个文本框：
ReplaceVersionWithExactValueInPath 改变这个：
到这里：
Controller 类现在如下所示：
[Route("api/v{version:apiVersion}/[controller]")]
[ApiVersion("1")]
[ApiVersion("2")]
public class ValuesController : Controller
{
// GET api/values
[HttpGet]
public IEnumerable<string> Get()
{
return new string[] { "value1", "value2" };
}
// GET api/values/5
[HttpGet("{id}")]
public string Get(int id)
{
return "value";
}
// POST api/values
[HttpPost]
public void Post([FromBody]string value)
{
}
// PUT api/values/5
[HttpPut("{id}")]
public void Put(int id, [FromBody]string value)
{
}
// DELETE api/values/5
[HttpDelete("{id}")]
public void Delete(int id)
{
}
[HttpGet("otherget/one")]
[MapToApiVersion("2")]
public IEnumerable<string> Get2()
{
return new string[] { "value1", "value2" };
}
/// <summary>
/// THIS ONE WILL BE EXCLUDED FROM SWAGGER Ui, BECAUSE v3 IS NOT SPECIFIED. 'DocInclusionPredicate' MAKES THE
/// TRICK
/// </summary>
/// <returns></returns>
[HttpGet("otherget/three")]
[MapToApiVersion("3")]
public IEnumerable<string> Get3()
{
return new string[] { "value1", "value2" };
}
}
代码：https://gist.github.com/Alezis/bab8b559d0d8800c994d065db03ab53e