NSwag .NET Core API版本控制配置

Question

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

我正在使用带有NSwag（v11.18.2）的.NET Core 2.1。我还安装了Microsoft.AspNetCore.Mvc.Versioning NuGet程序包。

我已经在Google上搜索了一些配置示例，但是我发现的唯一有用的链接是this。

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

1. 请注意，没有最后config的设置（Title，Description在任何2路等）生效。仅当我将它们添加到每个单独的配置中时，它才起作用。因此，我也想知道是否有可能避免这种情况，因为API的常规配置可以是版本无关的（标题，说明等...）。
2. 由于上述链接中讨论的NSwag和Microsoft API Versioning软件包的问题是在2-3个月前打开的（并且也是NSwag版本），所以我想知道它是否现在已真正解决，在这种情况下，即正确的配置设置。
3. 尽管该版本在控制器的配置中是明确的，但仍需要将其作为控制器方法的强制输入参数，当然我不希望这样做！见图片：

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

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. 请创建一个包含特定问题和重现的问题，另请查看存储库中的现有测试
3. v11.18.3 已修复