1

我在我的 WebAPI 项目上设置了 Swagger/Swashbuckle。我遵循了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

我尝试简单地替换UI{version}中工作RelativePath的ApiExplorer，但破坏了测试功能，因为它{version}被更改为query参数而不是path，这不是我的 API 的配置方式。

我是否可以ApiExplorer在 swagger 构建文档之前修改值，同时仍保留测试功能？

4

2 回答 2

1

API 版本控制的 API Explorer 现在支持开箱即用的行为，使用：

options.SubstituteApiVersionInUrl = true

这将为您完成替换工作，并从操作描述符中删除 API 版本参数。您通常不需要更改应用于替换值的默认格式，但您可以使用以下方法更改它：

options.SubstitutionFormat = "VVV"; // this is the default
于 2018-03-26T02:41:19.307 回答
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"));

            });

Swagger UI 的最终结果

于 2017-05-25T15:37:14.820 回答