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(1).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(1).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枚举值,再进行判断,实现一个接口可以归为多个分组。

 

posted on 2019-04-20 09:37  菜工  阅读(5277)  评论(6编辑  收藏  举报

导航