EnableSwagger routeTemplate参数的目的是什么?

时间:2018-06-29 16:48:27

标签: c# .net asp.net-web-api swagger swashbuckle

我正在尝试解决一个问题,其中我的控制器装饰有这样的RoutePrefix:

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

但是Swagger像这样在目录中显示网址:

/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 :(得分:2)

据我所知,它允许自定义路由,而传统ASP.NET MVC / Web API路由配置未定义该路由,如下所示:

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

尽管您可能在WebApiConfig.cs文件中找到类似上述的内容,但是可以使用RouteTemplate更改Swagger JSON端点的路径。

自述文件:

  

默认情况下,Swagger JSON将在以下路由中公开-   “ /swagger/{documentName}/swagger.json”。如有必要,可以更改   启用S​​wagger中间件时可以使用此功能。自定义路线必须包括   {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根据路由将所有内容连接起来。 / p>