Какова цель параметра EnableSwagger routeTemplate?

Question

Я пытаюсь решить проблему, когда мои контроллеры украшены RoutePrefix следующим образом:

[RoutePrefix("api/v{version:apiVersion}/users")]

Но Swagger отображает URL в оглавлении следующим образом:

/api/v{version}/users/search

Я экспериментировал с параметром EnableSwagger routeTemplate, но в итоге получил ошибки, отображаемые во встроенных комментариях ниже:

GlobalConfiguration.Configuration
    .EnableSwagger(
    //"v{version:apiVersion}",  //A potentially dangerous Request.Path value was detected from the client (:).
    //"v{version}",             //Can't read swagger JSON from http://localhost:52056/v{version}
    //"{version}",              //Can't read swagger JSON from http://localhost:52056/{version}
    //"v2",                     //Can't read swagger JSON from http://localhost:52056/v2
    c =>
    {
        //...
    }
}

Как правильно использовать параметр EnableSwagger routeTemplate? И к каким типам сценариев использования предназначен этот параметр? Этот параметр предназначен для решения конкретной проблемы, которую я описал? Или я пытаюсь использовать этот параметр неправильно или неправильно?

Answer 1

Насколько я понимаю, это позволяет не задавать настройку маршрутов традиционными конфигами маршрутов ASP.NET MVC/Web API, например:

config.Routes.MapHttpRoute(
                name: "DefaultApi",
                routeTemplate: "api/{controller}/{id}",
                defaults: new { id = RouteParameter.Optional }
            );

Хотя вы можете найти что-то подобное в WebApiConfig.cs файл, вы можете изменить путь для конечных точек Swagger JSON, используя RouteTemplate,

Из файла Readme:

По умолчанию Swagger JSON будет представлен по следующему маршруту - "/swagger/ enjdocumentName‹/swagger.json". При необходимости вы можете изменить это при включении промежуточного программного обеспечения Swagger. Пользовательские маршруты ДОЛЖНЫ включать параметр {documentName}.

app.UseSwagger(c =>
{
    c.RouteTemplate = "api-docs/{documentName}/swagger.json";
});

ПРИМЕЧАНИЕ. Если вы используете промежуточное ПО SwaggerUI, вам также необходимо обновить его конфигурацию, чтобы отразить новые конечные точки:

app.UseSwaggerUI(c =>
{
    c.SwaggerEndpoint("/api-docs/v1/swagger.json", "My API V1");
})

Для API управления версиями вы можете написать собственный распознаватель, скорее всего. И к этому моменту, я думаю, вы сделали это немного сложнее для себя, версионируя свои API так. Если вы просто создали v1/{resource} а также v2/{resource} Вы могли бы, конечно, написать собственный распознаватель, чтобы посмотреть версию в маршруте и использовать c.MultipleApiVersions() API, чтобы связать все по маршруту.