翼度科技»论坛 编程开发 .net 查看内容

ASP.NET Core Web API Swagger 按标签Tags分组排序显示

5

主题

5

帖子

15

积分

新手上路

Rank: 1

积分
15
需求


  • swagger页面按标签Tags分组显示。
  • 没有打标签Tags的接口,默认归到"未分组"。
  • 分组内按接口路径排序
说明

为什么没有使用GroupName对接口进行分组?
暂时不需要,以及不想点击swagger页面右上角那个下拉框。
当然Tags和GroupName不冲突,不影响通过GroupName再分组显示。
如何实现

1. 为controller或action打上标签

TagsAttribute特性可以打在controller类上,也可以打在action方法上,一个类或方法上可以打多个标签。示例:
  1. [Tags("标签1", "标签2")]
复制代码
有个小坑,Tags要么打在controller上,要么打在action上,不能同时打。
2. 实现IDocumentFilter接口

清空原有的Tags,并按接口类或方法上的标签重新添加Tags,然后排序。
  1. using Microsoft.OpenApi.Models;
  2. using Swashbuckle.AspNetCore.SwaggerGen;
  3. using Utils;
  4. namespace DotnetDatamining.Filters
  5. {
  6.     /// <summary>
  7.     /// Workaround for https://github.com/domaindrivendev/Swashbuckle.AspNetCore/issues/2162
  8.     /// When adding XML controller descriptions to the swagger description document,
  9.     /// controllers are listed out of alphabetical order.
  10.     ///
  11.     /// This filter explicitly reorders them.
  12.     /// </summary>
  13.     public class TagReorderDocumentFilter : IDocumentFilter
  14.     {
  15.         /// <summary>
  16.         /// Allows customization of the swagger description document
  17.         /// </summary>
  18.         /// <param name="swaggerDoc">The generated swagger description document</param>
  19.         /// <param name="context">Context information</param>
  20.         public void Apply(OpenApiDocument swaggerDoc, DocumentFilterContext context)
  21.         {
  22.             swaggerDoc.Tags.Clear(); //清空Tags
  23.             //重新添加Tags
  24.             foreach (var path in swaggerDoc.Paths)
  25.             {
  26.                 foreach (var o in path.Value.Operations)
  27.                 {
  28.                     foreach (var tag in o.Value.Tags)
  29.                     {
  30.                         swaggerDoc.Tags.Add(tag);
  31.                     }
  32.                 }
  33.             }
  34.             //排序
  35.             swaggerDoc.Tags = swaggerDoc.Tags
  36.                 .OrderBy(tag => TinyPinYinUtil.GetPinYin(tag.Name)) //按汉字拼音排序
  37.                 .ToList();
  38.         }
  39.     }
  40. }
复制代码
3. Swagger配置
  1. //swagger配置
  2. builder.Services.AddSwaggerGen(c =>
  3. {
  4.     c.SwaggerDoc("v1", new OpenApiInfo
  5.     {
  6.         Title = "XXX",
  7.         Version = "1.0",
  8.         Description = "XXX"
  9.     });
  10.     var path = Path.Combine(AppContext.BaseDirectory, "DotnetDatamining.xml"); // xml文档绝对路径
  11.     c.IncludeXmlComments(path, true); // 显示控制器层注释
  12.     c.TagActionsBy(a =>
  13.     {
  14.         var tagAttr = a.ActionDescriptor.EndpointMetadata.OfType<TagsAttribute>().FirstOrDefault();
  15.         if (tagAttr != null)
  16.         {
  17.             return tagAttr.Tags.ToList();
  18.         }
  19.         return new List<string>() { "未分组" };
  20.     });
  21.     c.DocumentFilter<TagReorderDocumentFilter>(); // Workaround: After adding XML controller descriptions, they are listed out of alphabetical order
  22.     c.OrderActionsBy(a => a.RelativePath); // 对Action排序
  23. });
复制代码
上述代码说明

(1) 使用TagReorderDocumentFilter过滤器
  1. c.DocumentFilter<TagReorderDocumentFilter>();
复制代码
(2) 对Action按标签分组

没有打标签Tags的接口,默认归到"未分组"。
  1. c.TagActionsBy(a =>
  2. {
  3.     var tagAttr = a.ActionDescriptor.EndpointMetadata.OfType<TagsAttribute>().FirstOrDefault();
  4.     if (tagAttr != null)
  5.     {
  6.         return tagAttr.Tags.ToList();
  7.     }
  8.     return new List<string>() { "未分组" };
  9. });
复制代码
(2) 分组内对Action按接口路径排序
  1. c.OrderActionsBy(a => a.RelativePath);
复制代码
效果图

分组按汉字拼音排序,分组内按接口路径排序

在实现过程中遇到的问题


  • 部署到linux系统,中文拼音排序问题,不想修改linux系统配置,于是修改代码,通过TinyPinyin.Net库实现。
  • 分组排序和分组内接口排序问题
    一个接口可以打多个标签。如果是单个标签,可以通过OrderActionsBy对分组和接口同时排序。如果是多个标签,则无法通过OrderActionsBy对分组和接口同时排序,只能对接口进行排序。
    可以在TagReorderDocumentFilter过滤器中对标签进行排序,但Tags中都是controller默认的标签,所以要先清空,再重新添加,然后再排序。
为了解决这些问题,提供一个容易阅读和查找的swagger文档目录,断断续续花费了很长时间才算解决。

来源:https://www.cnblogs.com/s0611163/archive/2023/03/15/17218134.html
免责声明:由于采集信息均来自互联网,如果侵犯了您的权益,请联系我们【E-Mail:cb@itdo.tech】 我们会及时删除侵权内容,谢谢合作!

本帖子中包含更多资源

您需要 登录 才可以下载或查看,没有账号?立即注册

x

举报 回复 使用道具