ASP.NET Core Web API Swagger 按标签Tags分组排序显示
需求[*]swagger页面按标签Tags分组显示。
[*]没有打标签Tags的接口，默认归到"未分组"。
[*]分组内按接口路径排序
说明
为什么没有使用GroupName对接口进行分组？
暂时不需要，以及不想点击swagger页面右上角那个下拉框。
当然Tags和GroupName不冲突，不影响通过GroupName再分组显示。
如何实现
1. 为controller或action打上标签
TagsAttribute特性可以打在controller类上，也可以打在action方法上，一个类或方法上可以打多个标签。示例：
有个小坑，Tags要么打在controller上，要么打在action上，不能同时打。
2. 实现IDocumentFilter接口
清空原有的Tags，并按接口类或方法上的标签重新添加Tags，然后排序。
using Microsoft.OpenApi.Models;
using Swashbuckle.AspNetCore.SwaggerGen;
using Utils;
namespace DotnetDatamining.Filters
{
/// <summary>
/// Workaround for https://github.com/domaindrivendev/Swashbuckle.AspNetCore/issues/2162
/// When adding XML controller descriptions to the swagger description document,
/// controllers are listed out of alphabetical order.
///
/// This filter explicitly reorders them.
/// </summary>
public class TagReorderDocumentFilter : IDocumentFilter
{
/// <summary>
/// Allows customization of the swagger description document
/// </summary>
/// <param name="swaggerDoc">The generated swagger description document</param>
/// <param name="context">Context information</param>
public void Apply(OpenApiDocument swaggerDoc, DocumentFilterContext context)
{
swaggerDoc.Tags.Clear(); //清空Tags
//重新添加Tags
foreach (var path in swaggerDoc.Paths)
{
foreach (var o in path.Value.Operations)
{
foreach (var tag in o.Value.Tags)
{
swaggerDoc.Tags.Add(tag);
}
}
}
//排序
swaggerDoc.Tags = swaggerDoc.Tags
.OrderBy(tag => TinyPinYinUtil.GetPinYin(tag.Name)) //按汉字拼音排序
.ToList();
}
}
}3. Swagger配置
//swagger配置
builder.Services.AddSwaggerGen(c =>
{
c.SwaggerDoc("v1", new OpenApiInfo
{
Title = "XXX",
Version = "1.0",
Description = "XXX"
});
var path = Path.Combine(AppContext.BaseDirectory, "DotnetDatamining.xml"); // xml文档绝对路径
c.IncludeXmlComments(path, true); // 显示控制器层注释
c.TagActionsBy(a =>
{
var tagAttr = a.ActionDescriptor.EndpointMetadata.OfType<TagsAttribute>().FirstOrDefault();
if (tagAttr != null)
{
return tagAttr.Tags.ToList();
}
return new List<string>() { "未分组" };
});
c.DocumentFilter<TagReorderDocumentFilter>(); // Workaround: After adding XML controller descriptions, they are listed out of alphabetical order
c.OrderActionsBy(a => a.RelativePath); // 对Action排序
});上述代码说明
(1) 使用TagReorderDocumentFilter过滤器
c.DocumentFilter<TagReorderDocumentFilter>();(2) 对Action按标签分组
没有打标签Tags的接口，默认归到"未分组"。
c.TagActionsBy(a =>
{
var tagAttr = a.ActionDescriptor.EndpointMetadata.OfType<TagsAttribute>().FirstOrDefault();
if (tagAttr != null)
{
return tagAttr.Tags.ToList();
}
return new List<string>() { "未分组" };
});(2) 分组内对Action按接口路径排序
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】 我们会及时删除侵权内容，谢谢合作！
页:
[1]