NSwag .NET Core API 版本控制配置

Question

我想准备我的 .NET Core Web API 项目，以便可以管理和记录 API 的多个版本，根据符合 REST 服务标准。

我正在使用 .NET Core 2.1 和 NSwag (v11.18.2)。我还安装了 Microsoft.AspNetCore.Mvc.Versioning NuGet 包。

我已经用 Google 搜索了一些配置示例，但我找到的唯一有用的 link 是 this.

我现在可以获取两个 API 版本的 Swagger 页面，但有一些问题：

请注意，最后 config 设置中的 none（Title、Description 等）对 2 条路线中的任何一条路线都有效。仅当我将它们添加到每个单独的配置时它才有效。所以我也想知道是否可以避免这种情况，因为 API 的一般配置可以是独立于版本的（标题、描述等...）。
由于上面讨论的 NSwag 和 Microsoft API 版本控制包的问题 link，是在 2-3 个月前（以及 NSwag 版本）打开的，我想知道是否它现在已真正修复，在这种情况下，这是要设置的正确配置。
虽然版本在控制器的配置中是明确的，但它仍然是控制器方法的强制输入参数，当然我不希望这样！见图：

因此，按照该示例，我的实际配置如下所示：

public void ConfigureServices(IServiceCollection services)
{
    services.AddMvc();
    services.AddApiVersioning(options =>
        {
            options.AssumeDefaultVersionWhenUnspecified = true;
            options.DefaultApiVersion = new ApiVersion(1, 0);
            options.ReportApiVersions = true;
        });
}

public void Configure(IApplicationBuilder app, IHostingEnvironment env)
{
    app.UseSwaggerWithApiExplorer(config =>
    {
        config.GeneratorSettings.OperationProcessors.TryGet<ApiVersionProcessor>().IncludedVersions = new[] { "1.0" };
        config.SwaggerRoute = "v1.0.json";
    });

    app.UseSwaggerWithApiExplorer(config =>
    {
        config.GeneratorSettings.OperationProcessors.TryGet<ApiVersionProcessor>().IncludedVersions = new[] { "2.0" };
        config.SwaggerRoute = "v2.0.json";
    });

    app.UseSwaggerUi3(typeof(Startup).GetTypeInfo().Assembly, config =>
    {
        config.SwaggerRoutes.Add(new SwaggerUi3Route("v1.0", "/v1.0.json"));
        config.SwaggerRoutes.Add(new SwaggerUi3Route("v2.0", "/v2.0.json"));

        config.GeneratorSettings.Title = "My API";
        config.GeneratorSettings.Description = "API functionalities.";
        config.GeneratorSettings.DefaultUrlTemplate = "{v:apiVersion}/{controller}/{action}/{id?}";
        config.GeneratorSettings.DefaultPropertyNameHandling = PropertyNameHandling.CamelCase
    });
}

这些是我的实际控制人：

[ApiController]
[ApiVersion("1.0")]
[Route("api/v{version:apiVersion}/[controller]/[action]")]
[SwaggerTag("Test1", Description = "Core operations on machines (v1.0).")]
public class MachinesController : Controller
{
    [HttpGet("{id}")]
    [ProducesResponseType((int)HttpStatusCode.OK)]
    public async Task<ActionResult<Machine>> Get(int id)
    {
        return await ...
    }
}

[ApiController]
[ApiVersion("2.0")]
[Route("api/v{version:apiVersion}/[controller]/[action]")]
[SwaggerTag("Test2", Description = "Core operations on machines (v2.0).")]
public class MachinesController : Controller
{
    [HttpGet("{id}")]
    [ProducesResponseType((int)HttpStatusCode.OK)]
    public async Task<ActionResult<Machine>> Get(int id)
    {
        return await ...
    }
}

Answer 1

它们在中间件中被忽略，因为它们是从设置中推断出来的，或者不适用于 api 资源管理器（模板）。但是标题和描述应该有效...
请创建具有特定问题的问题和一个 repro，同时检查 repo 中的现有测试
已在 v11.18.3 中修复

Answer 2

我相信从 NSwag 12.0.0 开始，对 API Explorer 的支持得到了显着改进。重要的是还引用了补充 API Explorer package for API versioning，以便向 NSwag 提供正确的信息。

API 提供的 Swagger sample application 版本控制使用 Swashbuckle，但设置与 NSwag 非常相似。您可以使用 IApiVersionDescriptionProvider 服务枚举应用程序中定义的所有 API 版本。这应该会显着简化您的 NSwag 配置。

您正在按 URL 段进行版本控制；因此，要解决问题 3，您只需配置 API Explorer a la:

services.AddVersionedApiExplorer( options => options.SubstituteApiVersionInUrl = true );

这会将路由模板中的 {version} 路由参数替换为相应的 API 版本值，并从 API 描述中删除 API 版本参数。

NSwag .NET Core API 版本控制配置

NSwag .NET Core API Versioning configuration

c#

.net-core

api-versioning

asp.net-core-webapi

nswag