Конфигурация управления версиями NSwag .NET Core API

Question

Я хотел бы подготовить свой проект .NET Core Web API, чтобы можно было управлять и документировать несколько версий API в соответствии со стандартами служб REST.

Я использую .NET Core 2.1 с NSwag (v11.18.2). Я также установил пакет NuGet для Microsoft.AspNetCore.Mvc.Versioning.

Я уже искал в Google несколько примеров конфигурации, но единственная полезная ссылка, которую я нашел, - это.

Теперь я могу получить страницы Swagger для обеих версий API, но с некоторыми проблемами:

1. Обратите внимание, что ни один из последних config настройки (Title, Descriptionи т. д.) действует на любом из 2 маршрутов. Это работает, только если я добавлю их на каждой отдельной конфигурации. Поэтому я также хотел бы знать, возможно ли этого избежать, поскольку общая конфигурация API может быть независимой от версии (заголовок, описание и т. Д.).
2. Поскольку проблема с NSwag и пакетом управления версиями Microsoft API, рассмотренная в приведенной выше ссылке, была открыта 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

Answer 2

Я считаю, что начиная с NSwag 12.0.0, значительно улучшена поддержка API Explorer. Важно, чтобы на дополнительный пакет API Explorer для управления версиями API также ссылались, чтобы соответствующая информация предоставлялась NSwag.

Образец приложения Swagger, предоставляемый API Versioning, использует Swashbuckle, но настройка будет очень похожа на NSwag. Вы можете использовать службу IApiVersionDescriptionProvider для перечисления всех версий API, определенных в вашем приложении. Это должно значительно упростить вашу конфигурацию NSwag.

Вы управляете версиями по сегментам URL; следовательно, для решения проблемы 3 вам просто нужно настроить API Explorer а-ля:

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

Это заменит {version} Параметр route в шаблоне маршрута с соответствующим значением версии API и удалите параметр версии API из описания API.