一、前言
接Swashbuckle技巧b篇，与Action相关的配置和操作，此处为c篇内容。
二、实践技巧
2.9 忽略过时控制器和过时Action
1）配置服务
编辑ConfigureServices函数中的AddSwaggerGen函数，
services.AddSwaggerGen(c => { ... #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 #region 忽略过时特性 //忽略标记过时的Action options.IgnoreObsoleteActions(); //忽略标记过时的Properties options.IgnoreObsoleteProperties(); #endregion ... };
2）添加案例控制器
新建控制器IgnoreObsoleteController，内容如下：
namespace swaggertestbase.Controllers.v1 { /// <summary> /// 忽略函数控制器 /// </summary> [Route("api/[controller]")] [ApiController] public class IgnoreObsoleteController : ControllerBase { /// <summary> /// 获取忽略函数数据 /// </summary> /// <returns>返回结果</returns> [Obsolete] [HttpGet] public string Get() { return "IgnoreObsolete"; } [HttpGet("{id}")] //直接直接使用ApiExplorerSettings设置属性IgnoreApi = true //在当前项目中该配置无效 [ApiExplorerSettings(IgnoreApi = true)] public string GetById(int id) { return "IgnoreObsolete"; } } }
运行效果如下，在v1组中并不存在对应的控制器以及对应过时的函数。
2.10 按照约定选择Action函数
1）自定义约定实现类
新建类ApiExplorerGetsOnlyConvention，实现IActionModelConvention接口，进行ActionModelConvention的自定义规则实现。
/// <summary> /// 自定义实现只显示Get请求的Action模型 /// </summary> public class ApiExplorerGetsOnlyConvention : IActionModelConvention { public void Apply(ActionModel action) { //依据请求是否为get请求处理是是否参与apijson的数据接口生成 action.ApiExplorer.IsVisible = action.Attributes.OfType<HttpGetAttribute>().Any(); } }
2）添加约定到服务配置
services.AddControllers(configure => { //添加自定义apiexplor.groupname控制器模型属性 //configure.Conventions.Add(new ApiExplorerGroupVersionConvention()); //自定义实现只显示Get请求的Action模型 configure.Conventions.Add(new ApiExplorerGetsOnlyConvention()); });
在控制器WeatherForecastController中添加一个Post请求函数，
/// <summary> /// 获取Post数据 /// </summary> /// <returns>处理结果</returns> [HttpPost] public string Post() { return "处理结果"; }
运行效果：
2.11 自定义操作标签
默认Tag分组是以控制器名称为依据进行划分，也可以通过TagActionsBy函数进行配置。
1）默认分组
2）自定义Tags分组
修改ConfigureServices中AddSwaggerGen对应配置，以下为依据Action的请求方法进行分组的案例，需要注意的是IncludeXmlComments函数，需要使用默认配置，而不是设置IncludeXmlComments第二参数为true。
services.AddSwaggerGen(options => { ... #region 添加xml注释文件描述性信息 //获取当前执行程序集名称+.xml,作为实际xml注释文件名称 string filename = $"{Assembly.GetExecutingAssembly().GetName().Name}.xml"; //拼接路径-路径间隔符由系统决定 string path = System.IO.Path.Combine(System.AppContext.BaseDirectory, filename); //添加xml注释文件到swaggergen中用于生成api json //此时需要选择使用该函数的默认配置 options.IncludeXmlComments(path); #endregion #region 自定义Tags options.TagActionsBy(apidescr => { return new string[] { apidescr.HttpMethod }; }); #endregion ... }; services.AddControllers(configure => { //添加自定义apiexplor.groupname控制器模型属性 //configure.Conventions.Add(new ApiExplorerGroupVersionConvention()); //自定义实现只显示Get请求的Action模型 //configure.Conventions.Add(new ApiExplorerGetsOnlyConvention()); });
运行效果：
2.12 自定义Action排序操作
默认情况下，Action能够按Swagger规范，在添加到分组之前进行排序操作，也可自定义排序规则，修改ConfigureServices中AddSwaggerGen对应配置，此处以自定义排序规则Controller与请求方法进行排序。
#region 自定义Tags options.TagActionsBy(apidescr => { return new string[] { apidescr.HttpMethod }; }); #endregion #region 自定义Tags排序 options.OrderActionsBy(apidesc => { //自定义Tag内的Action排序 return $"{apidesc.ActionDescriptor.RouteValues["controller"]}_{apidesc.HttpMethod}"; }); #endregion
运行效果：
