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

对乌粪痛加剿洗

需求

• 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;
5. namespace DotnetDatamining.Filters
6. {
7.     /// <summary>
8.     /// Workaround for https://github.com/domaindrivendev/Swashbuckle.AspNetCore/issues/2162
9.     /// When adding XML controller descriptions to the swagger description document,
10.     /// controllers are listed out of alphabetical order.
11.     ///
12.     /// This filter explicitly reorders them.
13.     /// </summary>
14.     public class TagReorderDocumentFilter : IDocumentFilter
15.     {
16.         /// <summary>
17.         /// Allows customization of the swagger description document
18.         /// </summary>
19.         /// <param name="swaggerDoc">The generated swagger description document</param>
20.         /// <param name="context">Context information</param>
21.         public void Apply(OpenApiDocument swaggerDoc, DocumentFilterContext context)
22.         {
23.             swaggerDoc.Tags.Clear(); //清空Tags
25.             //重新添加Tags
26.             foreach (var path in swaggerDoc.Paths)
27.             {
28.                 foreach (var o in path.Value.Operations)
29.                 {
30.                     foreach (var tag in o.Value.Tags)
31.                     {
32.                         swaggerDoc.Tags.Add(tag);
33.                     }
34.                 }
35.             }
37.             //排序
38.             swaggerDoc.Tags = swaggerDoc.Tags
39.                 .OrderBy(tag => TinyPinYinUtil.GetPinYin(tag.Name)) //按汉字拼音排序
40.                 .ToList();
41.         }
42.     }
43. }

复制代码

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】 我们会及时删除侵权内容，谢谢合作！