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枚举值,再进行判断,实现一个接口可以归为多个分组。
Asp.net Core的Swagger接口根据模块、版本分组的更多相关文章
- .net core的Swagger接口文档使用教程(二):NSwag
上一篇介绍了Swashbuckle ,地址:.net core的Swagger接口文档使用教程(一):Swashbuckle 讲的东西还挺多,怎奈微软还推荐了一个NSwag,那就继续写吧! 但是和Sw ...
- asp.net core 使用 swagger 生成接口文档
参考地址:http://www.cnblogs.com/daxnet/p/6181366.html http://www.jianshu.com/p/fa5a9b76f3ed 微软参考文档:https ...
- Asp.Net Core配置Swagger
本文主要参考:Using Swagger with ASP.net Core 1.创建WebApi项目 本文使用ASP.Net Core Web API项目模板演示Swagger到使用,首先创建Web ...
- Asp.Net Core WebApi (Swagger+EF Core/Code First)
Swagger简介: Swagger™的目标是为REST APIs 定义一个标准的,与语言无关的接口,使人和计算机在看不到源码或者看不到文档或者不能通过网络流量检测的情况下能发现和理解各种服务的功能. ...
- ASP.NET CORE API Swagger+IdentityServer4授权验证
简介 本来不想写这篇博文,但在网上找到的文章博客都没有完整配置信息,所以这里记录下. 不了解IdentityServer4的可以看看我之前写的入门博文 Swagger 官方演示地址 源码地址 配置Id ...
- Asp.Net Core集成Swagger
工作中一个公司会有很多个项目,项目之间的交互经常需要编写 API 来实现,但是编写文档是一件繁琐耗时的工作,并且随着 API 的迭代,每次都需要去更新维护接口文档,很多时候由于忘记或者人员交替的愿意造 ...
- asp.net core 集成swagger ui
什么是Swagger? 说swagger 之前,我们先说一下OpenApi 规范. OpenApi 是一种和语言无关的用于描述RESTAPIs 接口功能的一种规范,对RESTAPIs 接口的描述包括: ...
- ASP.NET Core 奇技淫巧之接口代理转发
前言 先讲讲本文的开发背景吧.. 在如今前后端分离的大背景下,咱的客户又有要求啦~ 要前后端分离~ 然因为种种原因..没办法用用纯前端的框架(其实是学习成本高,又没钱请前端开发人员)... 所以最终决 ...
- 发布自己的第一版asp.net core的RESTful接口程序
使用window开发一个简单的asp.net Core的RESTfull程序,网上很多,这里不说,我是直接使用IDE自己生成的项目来发布的.没有修改过主要代码.在IDE里发布到本地目录,得到类似文件 ...
随机推荐
- Python3 randrange() 函数
描述 randrange() 方法返回指定递增基数集合中的一个随机数,基数缺省值为1. 语法 以下是 randrange() 方法的语法: import random random.randrange ...
- 一步一步理解 python web 框架,才不会从入门到放弃
要想清楚地理解 python web 框架,首先要清楚浏览器访问服务器的过程. 用户通过浏览器浏览网站的过程: 用户浏览器(socket客户端) 3. 客户端往服务端发消息 6. 客户端接收消息 7. ...
- Reading Code Is Hard
注: 以下内容引自: https://blogs.msdn.microsoft.com/ericlippert/2004/06/14/reading-code-is-hard/ Reading Cod ...
- 【最小生成树】UVA1494Qin Shi Huang's National Road System秦始皇修路
Description During the Warring States Period of ancient China(476 BC to 221 BC), there were seven ki ...
- bzoj3594 方伯伯的玉米田 树状数组优化dp
f[i][j]表示到第i位,使用了j次机会的最长不下降子序列长度 转移:f[i][j]=max(f[x][y])+1; x<i; y<=j; a[x]+y<=a[i]+j; 所以根据 ...
- otter代码在IDEA远程DEBUG方法
众所周知,Otter的代码打包后,是通过Jetty启动的,Otter代码的启动脚本中自带了开启Jetty远程DEBUG的脚本,所以我们只需要在启动Otter Manager和Otter Node的时候 ...
- BZOJ_1827_[Usaco2010 Mar]gather 奶牛大集会_树形DP
BZOJ_1827_[Usaco2010 Mar]gather 奶牛大集会_树形DP 题意:Bessie正在计划一年一度的奶牛大集会,来自全国各地的奶牛将来参加这一次集会.当然,她会选择最方便的地点来 ...
- 【Unity游戏开发】AssetBundle杂记--AssetBundle的二三事
一.简介 马三在公司大部分时间做的都是游戏业务逻辑和编辑器工具等相关工作,因此对Unity AssetBundle这块的知识点并不是很熟悉,自己也是有打算想了解并熟悉一下AssetBundle,掌握一 ...
- Python并发编程之深入理解yield from语法(八)
大家好,并发编程 进入第八篇. 直到上一篇,我们终于迎来了Python并发编程中,最高级.最重要.当然也是最难的知识点--协程. 当你看到这一篇的时候,请确保你对生成器的知识,有一定的了解.当然不了解 ...
- 我手写的简易tomcat
前述 自己手写的简易的tomcat,实现了tomcat的基本响应功能,项目代码已经上传到我的Github,刚刚开始学习这里,当前还存在很多问题 项目简述及代码 当我们的Web运行的时候,从浏览器发出的 ...