Asp.net Core的Swagger接口根据模块、版本分组

近期一直在学习Asp.net Core，微软的文档太难看，都是英文翻译过来的，很不友好，感谢这个博客，从壹开始前后端分离【 .NET Core2.0 +Vue2.0 】，让我入门了，刚学到这个Swagger时，我就有个需求，因为我之前写过的系统是分了不同的模块，模块里面再分控制器，不同模块经常会有相同名称的控制器，例如销售中心模块里有个合同管理控制器，采购中心模块里也有个合同管理控制器，而且我一个系统接口可能得上百个，那如果都在一个页面显示的话，那也太多了，所以我想能不能把接口进行分组。

在博客系统后面也有介绍到Swagger：API多版本控制，带来的思考，还有网上查到的【dotNet Core】Swagger下简单的给WebApi分组(我发现网上关于Asp.net Core的资料还是比较少)，再结合我自己的需求修改了一下。

先说下我的想法：

定义一个系统分组枚举Enum，包含我系统所有的控制器分组（或者版本），然后再定义一个特性Attribute，可以接收刚才那个Enum值，在需要分组的控制器类上面定义特性Attribute，Swagger根据系统分组枚举Enum的值进行分组，将特性Attribute的分组枚举值一样的归为同一个分组，没有加特性Attribute的归在无分组下，最终效果如下

下面是我的代码，理解为主，不用完全按我写的

基础Swagger的用法就不说的，具体可看 从壹开始前后端分离【 .NET Core2.0 +Vue2.0 】这个大师关于Swagger部分的教程，非常适合初级入门

在项目创建一个目录（ApiGroup），然后创建三个类，分别为ApiGroupAttribute.cs（控制器特性），ApiGroupNames.css（系统分组枚举），GroupInfoAttribute.cs（给系统分组枚举值增加相关信息的特性，这个主要是用于在Swagger分组时可关联Title，Version，Description值）

ApiGroupAttribute.cs代码如下

using Microsoft.AspNetCore.Mvc.ApiExplorer;
using System;
using System.Collections.Generic;
using System.Linq;
using System.Threading.Tasks;

namespace ItSys.ApiGroup
{
    /// <summary>
    /// 系统分组特性
    /// </summary>
    public class ApiGroupAttribute : Attribute, IApiDescriptionGroupNameProvider
    {
        public ApiGroupAttribute(ApiGroupNames name)
        {
            GroupName = name.ToString();
        }
        public string GroupName { get; set; }
    }
}

ApiGroupNames.cs代码如下

using System;
using System.Collections.Generic;
using System.Linq;
using System.Threading.Tasks;

namespace ItSys.ApiGroup
{
    /// <summary>
    /// 系统分组枚举值
    /// </summary>
    public enum ApiGroupNames
    {
        [GroupInfo(Title ="登录认证",Description ="登录认证相关接口",Version ="v1")]
        Auth,
        [GroupInfo(Title = "IT", Description = "登录认证相关接口")]
        It,
        [GroupInfo(Title = "人力资源", Description = "登录认证相关接口")]
        Hr,
        Cw
    }
}

GroupInfoAttribute.cs代码如下

using System;
using System.Collections.Generic;
using System.Linq;
using System.Threading.Tasks;

namespace ItSys.ApiGroup
{
    /// <summary>
    /// 系统模块枚举注释
    /// </summary>
    public class GroupInfoAttribute : Attribute
    {
        public string Title { get; set; }
        public string Version { get; set; }
        public string Description { get; set; }
    }
}

打开Startup.cs文件修改ConfigureServices方法（为了方便查看，只列出关于Swagger分组的关键代码）

public void ConfigureServices(IServiceCollection services)
{

    #region Swagger
    services.AddSwaggerGen(options =>
    {
        //遍历ApiGroupNames所有枚举值生成接口文档，Skip(1)是因为Enum第一个FieldInfo是内置的一个Int值
        typeof(ApiGroupNames).GetFields().Skip().ToList().ForEach(f =>
        {
            //获取枚举值上的特性
            var info = f.GetCustomAttributes(typeof(GroupInfoAttribute), false).OfType<GroupInfoAttribute>().FirstOrDefault();
            options.SwaggerDoc(f.Name, new Swashbuckle.AspNetCore.Swagger.Info
            {
                Title = info?.Title,
                Version = info?.Version,
                Description = info?.Description
            });
        });
        //没有加特性的分到这个NoGroup上
        options.SwaggerDoc("NoGroup", new Swashbuckle.AspNetCore.Swagger.Info
        {
            Title = "无分组"
        });
        //判断接口归于哪个分组
        options.DocInclusionPredicate((docName, apiDescription) =>
        {
            if (docName == "NoGroup")
            {
                //当分组为NoGroup时，只要没加特性的都属于这个组
                return string.IsNullOrEmpty(apiDescription.GroupName);
            }
            else
            {
                return apiDescription.GroupName == docName;
            }
        });
}

修改Configure方法

public void Configure(IApplicationBuilder app, IHostingEnvironment env)
{

    #region Swagger
    app.UseSwagger();
    app.UseSwaggerUI(options =>
    {
        //遍历ApiGroupNames所有枚举值生成接口文档，Skip(1)是因为Enum第一个FieldInfo是内置的一个Int值
        typeof(ApiGroupNames).GetFields().Skip().ToList().ForEach(f =>
        {
            //获取枚举值上的特性
            var info = f.GetCustomAttributes(typeof(GroupInfoAttribute), false).OfType<GroupInfoAttribute>().FirstOrDefault();
            options.SwaggerEndpoint($"/swagger/{f.Name}/swagger.json", info != null ? info.Title : f.Name);

        });
        options.SwaggerEndpoint("/swagger/NoGroup/swagger.json", "无分组");
    });
    #endregion
}

然后你F6生成一下，没出错的话，就Ctrl+F5看看，正常的话就会在Swagger右上角看到分组了。

在你需要进行分组的控制器上加上这个分组就ok了

目前是一个接口只归为一个分组，但可能实际中有些公用接口，会出现在多个分组模块里的，那可以将ApiGroupAttribute增加一个string[]或ApiGroupNames[]属性，接收多个枚举值，或者定义多个ApiGroupAttribute特性，不过在ConfigureServices里的Swagger的DocInclusionPredicate分组过滤方法里，就不能单判断GroupName参数了，可以利用参数ApiDescription反射得出接口控制器上的ApiGroupAttribute特性，获取所有的ApiGroupNames枚举值，再进行判断，实现一个接口可以归为多个分组。