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

时间：2021-03-06 01:06:10

需求

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

说明

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

如何实现

1. 为controller或action打上标签

TagsAttribute特性可以打在controller类上，也可以打在action方法上，一个类或方法上可以打多个标签。示例：

[Tags("标签1", "标签2")]

有个小坑，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);

效果图

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

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

在实现过程中遇到的问题

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

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



标签：

相关文章