经验首页 前端设计 程序设计 Java相关 移动开发 数据库/运维 软件/图像 大数据/云计算 其他经验
当前位置:技术经验 » 程序设计 » ASP.net » 查看文章
ASP.NET Core Web API Swagger 按标签Tags分组排序显示
来源:cnblogs  作者:0611163  时间:2023/3/17 9:00:39  对本文有异议

需求

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

说明

为什么没有使用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);

效果图

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

在实现过程中遇到的问题

  1. 部署到linux系统,中文拼音排序问题,不想修改linux系统配置,于是修改代码,通过TinyPinyin.Net库实现。
  2. 分组排序和分组内接口排序问题
    一个接口可以打多个标签。如果是单个标签,可以通过OrderActionsBy对分组和接口同时排序。如果是多个标签,则无法通过OrderActionsBy对分组和接口同时排序,只能对接口进行排序。
    可以在TagReorderDocumentFilter过滤器中对标签进行排序,但Tags中都是controller默认的标签,所以要先清空,再重新添加,然后再排序。

为了解决这些问题,提供一个容易阅读和查找的swagger文档目录,断断续续花费了很长时间才算解决。

原文链接:https://www.cnblogs.com/s0611163/p/17218134.html

 友情链接:直通硅谷  点职佳  北美留学生论坛

本站QQ群:前端 618073944 | Java 606181507 | Python 626812652 | C/C++ 612253063 | 微信 634508462 | 苹果 692586424 | C#/.net 182808419 | PHP 305140648 | 运维 608723728

W3xue 的所有内容仅供测试,对任何法律问题及风险不承担任何责任。通过使用本站内容随之而来的风险与本站无关。
关于我们  |  意见建议  |  捐助我们  |  报错有奖  |  广告合作、友情链接(目前9元/月)请联系QQ:27243702 沸活量
皖ICP备17017327号-2 皖公网安备34020702000426号