Asp.net core 如何从非默认版本文档中排除默认API路由版本

我有一个ASP.NET核心（3.1）API，它使用（4.1.1）库进行版本控制。项目设置为从URL读取版本，如果未指定版本，则使用默认版本（1）。示例控制器支持两个API版本（1和2），并且有两个相同的方法，每个版本一个。由于支持默认版本，控制器上有两个路由属性，一个没有版本，另一个有

当使用（5.6.3）库为API生成OpenAPI文档时，API版本1和2的文档都将包括非版本路由；“/Customer/{externalCustomerId}”。要解决的问题是，如何将Swagger生成配置为仅在默认版本的文档中包含非版本路由？鉴于以下代码，版本1的文档应为：

• /客户/{externalCustomerId}
• /v1/Customer/[externalCustomerId}

第2版的文档应为：

• /v2/Customer/{externalCustomerId}

启动：

public class Startup
{
    ... // Removed for brevity. Method below called from ConfigureServices(...).
    private static void ConfigureApiVersioning(IServiceCollection services)
    {
        services.AddVersionedApiExplorer(setup =>
        {
            setup.GroupNameFormat = "'v'V";
            setup.SubstituteApiVersionInUrl = true;
        });

        services.AddApiVersioning(setup =>
        {
            setup.AssumeDefaultVersionWhenUnspecified = true;
            setup.DefaultApiVersion = new ApiVersion(majorVersion: 1, minorVersion: 0);
            setup.ReportApiVersions = true;
            setup.ApiVersionReader = new UrlSegmentApiVersionReader();
        });
    }
}

控制器：

[Route("Customer")]
[Route("v{version:apiVersion}/Customer")]
[ApiVersion("1", Deprecated = true)]
[ApiVersion("2")]
[ApiController]
public class CustomerController : ControllerBase
{
    [HttpGet("{externalCustomerId}")]
    [MapToApiVersion("1")]
    public string Get()
    {
        return "Customer Api v1 responded with 200 ok";
    }

    [HttpGet("{externalCustomerId}")]
    [MapToApiVersion("2")]
    public string GetV2()
    {
        return "Customer Api v2 responded with 200 ok";
    }
}

是否可以（应该）以某种方式使用

swagggenoptions.DocInclusionPredicate（）

解决这个问题？我尝试了一下，但无法找到从谓词的

ApiVersion

获取默认API版本的方法

---

一个选项可能是从

DefaultApiVersionDescriptionProvider

（或实现

IApiVersionDescriptionProvider

）继承以访问Options属性，这将允许我们获取默认API版本，并在启动时为

SwaggerGenOptions.DocInclusionPredicate（）使用带闭包的谓词

，但这是一个好方法吗？还有什么其他选择吗？

有几种可能性：

• 使用

  DocInclusionPredicate

• 使用自定义IOperationFilter
• 使用自定义的IapDescriptionProvider

第一个可能是最简单的。由于所有版本正确的路由中都有route参数，因此您只需排除任何包含该参数的路由。例如：

c.DocInclusionPredicate（（d，api）=>！api.RelativePath.Contains（“v{version:apiVersion}”））

您需要删除/禁用

选项。替换版本inURL

；您无论如何都不会使用它

您应该仔细考虑您的API文档所传达的信息；这是误导性的。OpenAPI/Swagger文档将显示

2.0

的正确路径；但是，当客户端请求时，他们将获得

1.0

。这是因为您不允许指定任何版本，并且假定

1.0

。您可以这样做使用另一个IApiVersionSelector，如CurrentImplementationApiVersionSelector，但这只会使问题迎刃而解。版本控制的目的是让客户端可以明确地要求他们想要的版本