Asp.NetCore遇到Swagger（三）-Swashbuckle技巧b篇⽂章⽬录
⼀、前⾔
接上篇Swashbuckle技巧a篇，本篇⽂章继续讲解基于Swashbuckle的实践应⽤操作和配置。此处为b篇
⼆、实践技巧
2.4 修改Swagger Json请求路径
1）默认路径
{
"openapi":"3.0.1",
"info":{
"title":"swaggertestbase",
"version":"1.0"
},
"servers":[
{
"url":"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
...........
}
其中，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）运⾏效果
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);
}
2.7 按照约定⽣成Api分组
1）⾃定义约定
将控制器特定约定进⾏分组，以下为命名空间尾缀进⾏Api分组处理，
/// <summary>
/// ⾃定义ApiExplorGroup添加到控制器模型中
/// </summary>
public class ApiExplorerGroupVersionConvention : IControllerModelConvention
{
public void Apply(ControllerModel controller)
{
string namespac = controller.ControllerType.Namespace;
string groupname = namespac.Split(".").Last().ToLower();
asp查看源码配置uicontroller.ApiExplorer.GroupName = groupname;
}
}
2）添加约束
Startup.cs中的服务注册函数中修改AddControllers函数配置，
public void ConfigureServices(IServiceCollection services)
{
..........
//添加⾃定义upname控制器模型属性
services.AddControllers(configure =>{
configure.Conventions.Add(new ApiExplorerGroupVersionConvention());
});
}
3）修改命名空间
修改控制器WeatherForecastController与ValuesController的命名空间分别为v1和v2，//WeatherForecastController.cs
namespace
{
/// <summary>
/// 天⽓预报服务
/// </summary>
[ApiController]
[Route("[controller]")]
public class WeatherForecastController : ControllerBase
{
.......
}
}
//ValuesController.cs
namespace
{
[ApiController]
[Route("api/[controller]")]
[ApiExplorerSettings(GroupName ="v2")]
public class ValuesController : ControllerBase
{
.......
}
}
运⾏效果中，会发现，切换到ggcy v2时，将不再包含天⽓预报相关控制器和api
2.8 ⾃定义Action分组规则判定条件
1）引⽤依赖
Nuget引⽤Microsoft.AspNetCore.Mvc.Versioning 5.0.0
版权声明：本站内容均来自互联网，仅供演示用，请勿用于商业和其他非法用途。如果侵犯了您的权益请与我们联系QQ:729038198，我们将在24小时内删除。
发表评论