一、前言
接上篇Swashbuckle技巧a篇，本篇文章继续讲解基于Swashbuckle的实践应用操作和配置。此处为b篇
二、实践技巧
2.4 修改Swagger Json请求路径
1）默认路径
请求http://localhost:5000/swagger/v1/swagger.json，可查看到Swagger Json结构如下：
{ "openapi": "3.0.1", "info": { "title": "swaggertestbase", "version": "1.0" }, "servers": [ { "url": "http://localhost:5000" } ], "paths": { "/WeatherForecast": { "get": { "tags": [ "WeatherForecast" ] } } } }
2）自定义路径
自定义时，需要进行进行模板配置查看和依据实际需求机型节点配置，为Swagger中间件配置SwaggerOptions的RouteTemplate，对应的swagger-ui需要请求的Swagger Json地址也需要进行修改，
public void Configure(IApplicationBuilder app, IWebHostEnvironment env) { .......... #region Swagger中间件相关 //添加swagger配置，并启动中间件 app.UseSwagger(options => { options.RouteTemplate = "api-docs/{documentName}/swaggerapi.json"; } ); //启用Swagger-ui中间件，并配置swagger json的请求终节点 app.UseSwaggerUI(options => { options.SwaggerEndpoint("/api-docs/v1/swaggerapi.json","ggcy docs"); }); #endregion ........... }
Swagger Json访问地址变更为http://localhost:5000/api-docs/v1/swaggerapi.json内容不变
其中，RouteTemplate对应的值api-docs/{documentName}/swaggerapi.json，表示对应自定义的匹配路由，在启用SwaggerUI中间件时SwaggerEndpoint指定对应需要访问的Swagger Json，访问路径为/api-docs/v1/swaggerapi.json，其中v1为匹配到{documentName}，框架默认的文档名称为v1
2.5 修改文档swagger-ui访问前缀
1）修改前缀
默认情况下，访问Api文档，访问路径一般是xxxxx/swagger/index.html，前缀为swagger，需要自定义前缀时需要进行如下操作：
public void Configure(IApplicationBuilder app, IWebHostEnvironment env) { .......... #region Swagger中间件相关 //添加swagger配置，并启动中间件 app.UseSwagger(options => { options.RouteTemplate = "{documentName}/swaggerapi.json"; } ); //启用Swagger-ui中间件，并配置swagger json的请求终节点 app.UseSwaggerUI(options => { options.RoutePrefix = "api-docs"; options.SwaggerEndpoint("/v1/swaggerapi.json","ggcy docs"); }); #endregion ........... }
修改前缀的同时，也需要将Swagger中间件配置中RouteTemplate为{documentName}/swaggerapi.json，便于swagger-ui前端请求道对应带有前缀的swagger Json
2）运行效果
运行程序，访问地址http://localhost:5000/api-docs/index.html，出现如下结果
2.6 显示标签描述
1）加载xml注释文件
使用注释文件xml时，需要注意添加.xml文件引入时，注册服务时函数的参数值，
services.AddSwaggerGen(options => { ............... //获取执行目录下的所有解释文件.xml Directory.GetFiles(AppDomain.CurrentDomain.BaseDirectory, "*.xml").ToList().ForEach(file => { options.IncludeXmlComments(file,true); }); ................ });
IncludeXmlComments参数解释如下：
// // 摘要: // 基于 XML 注释文件为操作、参数和模式注入人性化的描述 // // 参数: // swaggerGenOptions: // // filePath: // 包含 XML 注释的文件的绝对路径 // // includeControllerXmlComments: // 用于指示是否应使用控制器 XML 注释（即摘要）的标志 // 分配标签描述。 如果需要要自定义默认值，请不要设置此标志 // 通过 TagActionsBy 标记操作。 public static void IncludeXmlComments(this SwaggerGenOptions swaggerGenOptions, string filePath, bool includeControllerXmlComments = false) { swaggerGenOptions.IncludeXmlComments(() => new XPathDocument(filePath),includeControllerXmlComments); }
