文章目录
一、前言
接上篇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);
}
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();
controller.ApiExplorer.GroupName = groupname;
}
}
2)添加约束
Startup.cs
中的服务注册函数中修改AddControllers
函数配置,
public void ConfigureServices(IServiceCollection services)
{
..........
//添加自定义apiexplor.groupname控制器模型属性
services.AddControllers(configure => {
configure.Conventions.Add(new ApiExplorerGroupVersionConvention());
});
}
3)修改命名空间
修改控制器WeatherForecastController
与ValuesController
的命名空间分别为v1
和v2
,
//WeatherForecastController.cs
namespace swaggertestbase.Controllers.v1
{
/// <summary>
/// 天气预报服务
/// </summary>
[ApiController]
[Route("[controller]")]
public class WeatherForecastController : ControllerBase
{
.......
}
}
//ValuesController.cs
namespace swaggertestbase.Controllers.v2
{
[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
2)添加判定规则
修改服务注册中DocInclusionPredicate
的ApiDescription.GroupName
判定逻辑,实现依据version
特性进行Api
分组
public void ConfigureServices(IServiceCollection services)
{
services.AddSwaggerGen(
options =>
{
...........
#region 自定义DocInclusionPredicate判定规则
options.DocInclusionPredicate((docName, apiDesc) => {
//判定当前执行是否为函数对象
if (!apiDesc.TryGetMethodInfo(out MethodInfo methodInfo))
return false;
//获取函数对应的自定义特性ApiVersionAttribute对应的版本集合
var versions = methodInfo.GetCustomAttributes(true)
.OfType<ApiVersionAttribute>()
.SelectMany(x => x.Versions);
//判定版本集合中是否与当前文档匹配
return versions.Any(x => $"v{x}" == docName);
});
#endregion
}
);
.........
}
3)添加案例控制器
创建Api
控制器DocInclusionController
,设定Version
特性
namespace swaggertestbase.Controllers
{
/// <summary>
/// DocInclusion控制器
/// </summary>
[Route("api/[controller]")]
[ApiController]
public class DocInclusionController : ControllerBase
{
/// <summary>
/// 获取DocInclusion数据
/// </summary>
/// <returns>查询结果</returns>
/// <remarks>
/// GET:
/// api/DocInclusionController
/// </remarks>
[HttpGet]
[ApiVersion("1")]
public IEnumerable<string> Get()
{
return new string[] { "value1", "value2" };
}
}
}
运行效果: