Какова цель параметра EnableSwagger routeTemplate? - PullRequest
Новая
       7

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

0 голосов
/ 29 июня 2018

Я пытаюсь решить проблему, когда мои контроллеры снабжены 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? И к каким типам сценариев использования предназначен этот параметр? Этот параметр предназначен для решения конкретной проблемы, которую я описал? Или я пытаюсь использовать этот параметр неправильно или неправильно?

1 Ответ

0 голосов
/ 29 июня 2018

Насколько я понимаю, настройка маршрутов не должна определяться традиционными конфигами маршрутов 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/{documentName}/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 для соединения всего в соответствии с маршрутом.

...