c# - NSwag .NET Core API 版本控制配置

Question

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

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

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

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

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

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

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

1. 它们在中间件中被忽略，因为它们是从设置中推断出来的，或者不适用于 api explorer(模板)。但是标题和描述应该有效...
2. 请针对特定问题创建一个问题和一个 repro，同时检查 repo 中的现有测试
3. 在 v11.18.3 中修复