我在我的WebAPI项目上设置了Swagger / Swashbuckle。我已经关注了guide from Microsoft,其中介绍了如何使用Swagger设置Aspnet.WebApi.Versioning。我的API有多个版本,因此路由属性中设置了{version}
参数,如下所示:
[ApiVersion("2")]
[RoutePrefix("api/{version:apiVersion}/values")]
public class AccountController : ApiController
{
[Route("UserInfo")]
public IEnumerable<string> Get()
{
return new string[] { "value1", "value2" };
}
}
我的问题是,这会在文档中显示的路径中显示{version}
属性,如下所示:
相反,我希望此路径属性实际上具有ApiVersion
属性中的值,以便对于阅读文档的客户端不会产生混淆。理想情况下,假设UrlDiscoverySelector设置为v2
,则上述路径应为:
/api/2/account/userinfo
/api/2/account/externallogin
/api/2/account/manageinfo
我尝试简单地替换用户界面中{version}
的{{1}}中的RelativePath
,但由于ApiExplorer
已更改为{{{version}
,因此打破了测试功能1}}参数而不是query
,这不是我的API配置方式。
是否有可能在swagger构建文档之前修改path
中的值,同时仍保留测试功能?
答案 0 :(得分:1)
用于API版本控制的API Explorer现在支持使用以下方式开箱即用的行为:
options.SubstituteApiVersionInUrl = true
这将为您执行替换工作,并从操作描述符中删除API版本参数。您通常不需要更改应用于替换值的默认格式,但您可以使用以下命令更改它:
options.SubstitutionFormat = "VVV"; // this is the default
答案 1 :(得分:0)
我正在使用Swashbuckle并使用了文档过滤器
public class VersionedOperationsFilter : IDocumentFilter
{
public void Apply(SwaggerDocument swaggerDoc, DocumentFilterContext context)
{
foreach (var apiDescriptionsGroup in context.ApiDescriptionsGroups.Items)
{
var version = apiDescriptionsGroup.GroupName;
foreach (ApiDescription apiDescription in apiDescriptionsGroup.Items)
{
apiDescription.RelativePath = apiDescription.RelativePath.Replace("{version}", version);
}
}
}
}
并在Startup.cs中的ConfigureServices方法中添加此过滤器:
services.AddMvc();
var defaultApiVer = new ApiVersion(1, 0);
services.AddApiVersioning(option =>
{
option.ReportApiVersions = true;
option.AssumeDefaultVersionWhenUnspecified = true;
option.DefaultApiVersion = defaultApiVer;
});
services.AddMvcCore().AddVersionedApiExplorer(e=>e.DefaultApiVersion = defaultApiVer);
services.AddSwaggerGen(
options =>
{
var provider = services.BuildServiceProvider().GetRequiredService<IApiVersionDescriptionProvider>();
options.DocumentFilter<VersionedOperationsFilter>();
//// add a swagger document for each discovered API version
//// note: you might choose to skip or document deprecated API versions differently
foreach (var description in provider.ApiVersionDescriptions)
{
options.SwaggerDoc(description.GroupName.ToString(),
CreateInfoForApiVersion(description));
}
//// integrate xml comments
options.IncludeXmlComments(Path.ChangeExtension(Assembly.GetEntryAssembly().Location, "xml"));
});