NSwag .NET Core API版本配置

Question

我想准備我的.NET Core Web API項目，以便根據REST服務標准管理和記錄多個版本的API。

我正在使用帶有NSwag的 .NET Core 2.1 （v11.18.2） 。 我還安裝了Microsoft.AspNetCore.Mvc.Versioning NuGet包。

我已經在谷歌搜索了一些配置示例，但我找到的唯一有用的鏈接就是這個 。

我現在能夠獲得兩個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. 請創建特定問題和repro的問題，還要檢查repo中的現有測試
3. 修復了v11.18.3

Answer 2

我相信從NSwag 12.0.0開始，API Explorer的支持得到了顯着改善。 重要的是，還要引用用於API版本控制的補充API Explorer包，以便向NSwag提供正確的信息。

API Versioning提供的Swagger示例應用程序使用Swashbuckle，但設置與NSwag非常相似。 您可以使用IApiVersionDescriptionProvider服務枚舉應用程序中定義的所有API版本。 這應該會顯着簡化您的NSwag配置。

您是按網址細分版本; 因此，要解決問題3，您只需要配置API Explorer a la：

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

這將使用相應的API版本值替換路徑模板中的{version} route參數，並從API描述中刪除API版本參數。