我使用ASP.NET Web API 2.1 Custom Route Attributes在 Visual Studio 2015 中创建了一个新的 asp.net web api 2 项目。
我正在使用 Swagger (SwashBuckle 5.0) 获取 API 文档,并希望每个版本都有文档,我设法获得了这个文档,但是 swagger ui 显示两个版本的相同 xml 注释。
版本 1 和 2 的 api/view 上的 xml 注释有一些不同之处,这些注释没有出现在 swagger ui 上。
版本 1
public class SwaggerConfig
{
public static void Register()
{
var thisAssembly = typeof(SwaggerConfig).Assembly;
GlobalConfiguration.Configuration
.EnableSwagger(c =>
{
c.MultipleApiVersions(
(apiDesc, targetApiVersion) => ResolveVersionSupportByRouteConstraint(apiDesc, targetApiVersion),
(vc) =>
{
vc.Version("2", "Swagger API V2");
vc.Version("1", "Swagger API V1");
});
c.IncludeXmlComments(GetXmlCommentsPath());
})
.EnableSwaggerUi(c =>
{
c.EnableDiscoveryUrlSelector();
});
}
private static string GetXmlCommentsPath()
{
return String.Format(@"{0}\bin\ChartOfAccounts.Api.XML", AppDomain.CurrentDomain.BaseDirectory);
}
private static bool ResolveVersionSupportByRouteConstraint(ApiDescription apiDesc, string targetApiVersion)
{
var attr = apiDesc.ActionDescriptor.GetCustomAttributes<VersionedRoute>().FirstOrDefault();
if (attr == null)
{
return true;
}
int targetVersion;
if (int.TryParse(targetApiVersion, out targetVersion))
{
return attr.AllowedVersion == targetVersion;
};
return true;
}
}
版本 1 控制器
[VersionedRoute("api/view", 1)]
public class ViewController : ApiController
{
private IChartManager _chartManager;
public ViewController(IChartManager chartManager)
{
_chartManager = chartManager;
}
/// <summary>
/// Returns a single view
/// </summary>
/// <param name="Id">Used to identify view. {Only Guid Accepted} </param>
/// <returns></returns>
public async Task<HttpResponseMessage> GetAsync(Guid Id)
{
Chart chart = await _chartManager.GetChartByIdAsync(Id);
return Request.CreateResponse(HttpStatusCode.OK, chart);
}
}
版本 2 API 控制器
[VersionedRoute("api/view", 2)]
public class Viewv2Controller : ApiController
{
private IChartManager _chartManager;
public Viewv2Controller(IChartManager chartManager)
{
_chartManager = chartManager;
}
/// <summary>
/// Returns a single view of the chart
/// </summary>
/// <param name="Id">Used to identify view</param>
/// <returns></returns>
public async Task<HttpResponseMessage> GetAsync(string Id)
{
Guid newGuidId;
if (Guid.TryParse(Id, out newGuidId))
{
Chart chart = await _chartManager.GetChartByIdAsync(newGuidId);
return Request.CreateResponse(HttpStatusCode.OK, chart);
}
return Request.CreateErrorResponse(HttpStatusCode.NotAcceptable, "Invalid Guid value for Parameter Id.");
}
}