当 API 版本在 URL 中时，为什么 Swagger 需要版本请求参数？

Question

我已经使用 Swashbuckle 和 MultipleApiVersions 实现了 Swagger，它就像一个魅力。但是我觉得当前设置需要 api-version 请求参数有点难看。我假设版本可以由 url /api/V1/Test 确定。

如何去掉 api-version 参数并指示 swagger 以 URL 为基础？

private static void SetupApiVersioningAndSwagger(IAppBuilder builder, AutofacWebApiDependencyResolver resolver)
        {
            // we only need to change the default constraint resolver for services that want urls with versioning like: ~/v{version}/{controller}
            var constraintResolver = new DefaultInlineConstraintResolver() { ConstraintMap = { ["apiVersion"] = typeof(ApiVersionRouteConstraint) } };
            var configuration = new HttpConfiguration();
            configuration.DependencyResolver = resolver;
            var httpServer = new HttpServer(configuration);

            // reporting api versions will return the headers "api-supported-versions" and "api-deprecated-versions"
            configuration.AddApiVersioning(o =>
            {
                o.ReportApiVersions = true;
                o.DefaultApiVersion = new ApiVersion(1, 0);
                o.AssumeDefaultVersionWhenUnspecified = true;
            });
            configuration.MapHttpAttributeRoutes(constraintResolver);

            // add the versioned IApiExplorer and capture the strongly-typed implementation (e.g. VersionedApiExplorer vs IApiExplorer)
            // note: the specified format code will format the version as "'v'major[.minor][-status]"
            var apiExplorer = configuration.AddVersionedApiExplorer(
                options =>
                {
                    options.GroupNameFormat = "'v'VVV";

                    // note: this option is only necessary when versioning by url segment. the SubstitutionFormat
                    // can also be used to control the format of the API version in route templates
                    options.SubstituteApiVersionInUrl = true;
                });

            configuration.EnableSwagger(
                             "{apiVersion}/swagger",
                             swagger =>
                             {
                                 // build a swagger document and endpoint for each discovered API version
                                 swagger.MultipleApiVersions(
                                     (apiDescription, version) => apiDescription.GetGroupName() == version,
                                     info =>
                                     {
                                         foreach (var group in apiExplorer.ApiDescriptions)
                                         {
                                             var description = string.Empty;

                                             if (@group.IsDeprecated)
                                             {
                                                 description += "This API version has been deprecated.";
                                             }

                                             info.Version(@group.Name, $"Force Search API v{@group.ApiVersion}")
                                                 .Description(description);
                                         }
                                     });

                                 swagger.UseFullTypeNameInSchemaIds();
                             })
                         .EnableSwaggerUi(swagger => swagger.EnableDiscoveryUrlSelector());

            builder.UseWebApi(httpServer);
        }

Answer 1

发生这种情况的原因是因为默认的 IApiVersionReader 是查询字符串和 URL 段方法的组合。这允许您使用任一方法而无需任何额外配置。阅读器实现还描述了使用 API 版本的位置和方式，以便可以将其报告为参数。由于在不同位置配置了 2 个阅读器，因此结果是 2 个参数。在您集成 OpenAPI/Swagger 之前，这通常不是问题。

默认配置如下：

configuration.AddApiVersioning(
    options => options.ApiVersionReader = ApiVersionReader.Combine(
        new QueryStringApiVersionReader(),
        new UrlSegmentApiVersionReader()));

解决方案

如下更新您的配置：

configuration.AddApiVersioning(
    options =>
    {
        options.ReportApiVersions = true;
        options.DefaultApiVersion = new ApiVersion(1, 0); // NOTE: already the default
        options.ApiVersionReader = new UrlSegmentApiVersionReader();
        options.AssumeDefaultVersionWhenUnspecified = true;
    });

之后，将只有一个参数。由于您已配置 options.SubstituteApiVersionInUrl = true，因此最终结果将是零 API 版本参数，因为该值直接烘焙到生成的 API 描述 URL 中。