.NET Core基础篇之:集成Swagger文档与自定义Swagger UI
Swagger
大家都不陌生,Swagger (OpenAPI)
是一个与编程语言无关的接口规范,用于描述项目中的 REST API
。它的出现主要是节约了开发人员编写接口文档的时间,可以根据项目中的注释生成对应的可视化接口文档。
OpenAPI 规范 (openapi.json)
OpenAPI
规范是描述 API
功能的文档。该文档基于控制器和模型中的 XML
和属性
注释。它是 OpenAPI
流的核心部分,用于驱动诸如 SwaggerUI
之类的工具。
.NET
平台下的两个主要实现Swagger
的包是 Swashbuckle 和 NSwag。今天我们从 Swashbuckle
开始了解。
基础功能
1、在包管理器搜索Swashbuckle.AspNetCore并安装。
2、在Startup.cs文件内的ConfigureServices方法内添加代码。
public void ConfigureServices(IServiceCollection services)
{
services.AddControllers();
services.AddSwaggerGen();
}
3、在Startup.cs文件内的Configure方法内添加代码。
app.UseSwagger();
app.UseSwaggerUI(options =>
{
options.SwaggerEndpoint("/swagger/v1/swagger.json", "v1");
options.RoutePrefix = string.Empty;
});
4、修改项目的launchSettings.json文件,将launchUrl的值改为:index.html
5、准备接口
[ApiController]
public class HomeController : ControllerBase
{
private readonly ILogger<HomeController> _logger;
public HomeController(ILogger<HomeController> logger)
{
_logger = logger;
}
/// <summary>
/// 获取用户信息
/// </summary>
/// <returns></returns>
[HttpGet("home/getuser")]
public string GetUser()
{
return "my name is dotnetboy";
}
/// <summary>
/// 登录成功
/// </summary>
/// <returns></returns>
[HttpPost("home/login")]
public string Login()
{
return "login success";
}
/// <summary>
/// 删除用户
/// </summary>
[HttpDelete("home/{id}")]
public string DeleteUser(string id)
{
return $"delete success,id={id}";
}
}
6、开启xml文档输出然后启动项目
扩展功能
项目描述
services.AddSwaggerGen(options =>
{
options.SwaggerDoc("v1", new OpenApiInfo
{
Title = "测试接口文档",
Version = "v1",
Description = "测试 webapi"
});
});
接口分组
在实际开发中,如果所有接口都展示在一起非常不利于相关人员查找,我们可以根据业务逻辑对相关接口进行分组,比如:登录、用户、订单、商品等等。
1、准备分组信息特性
/// <summary>
/// 分组信息特性
/// </summary>
public class GroupInfoAttribute : Attribute
{
/// <summary>
/// 标题
/// </summary>
public string Title { get; set; }
/// <summary>
/// 版本
/// </summary>
public string Version { get; set; }
/// <summary>
/// 描述
/// </summary>
public string Description { get; set; }
}
2、准备分组枚举
/// <summary>
/// 接口分组枚举
/// </summary>
public enum ApiGroupNames
{
[GroupInfo(Title = "登录认证", Description = "登录相关接口", Version = "v1")]
Login,
[GroupInfo(Title = "User", Description = "用户相关接口")]
User,
[GroupInfo(Title = "User", Description = "订单相关接口")]
Order
}
3、准备接口特性
/// <summary>
/// 分组接口特性
/// </summary>
public class ApiGroupAttribute : Attribute, IApiDescriptionGroupNameProvider
{
/// <summary>
///
/// </summary>
/// <param name="name"></param>
public ApiGroupAttribute(ApiGroupNames name)
{
GroupName = name.ToString();
}
/// <summary>
/// 分组名称
/// </summary>
public string GroupName { get; set; }
}
4、给不同接口加上特性
[ApiController]
public class HomeController : ControllerBase
{
private readonly ILogger<HomeController> _logger;
public HomeController(ILogger<HomeController> logger)
{
_logger = logger;
}
/// <summary>
/// 获取用户信息
/// </summary>
/// <returns></returns>
[HttpGet("home/getuser")]
[ApiGroup(ApiGroupNames.User)]
public string GetUser()
{
return "my name is dotnetboy";
}
/// <summary>
/// 登录成功
/// </summary>
/// <returns></returns>
[HttpPost("home/login")]
[ApiGroup(ApiGroupNames.Login)]
public string Login()
{
return "login success";
}
/// <summary>
/// 删除订单
/// </summary>
[HttpDelete("home/{id}")]
[ApiGroup(ApiGroupNames.Order)]
public string DeleteOrder(string id)
{
return $"delete success,id={id}";
}
/// <summary>
/// 留言
/// </summary>
[HttpDelete("home/message")]
public string DeleteUser(string msg)
{
return $"message:{msg}";
}
}
5、修改 ConfigureServices 方法的 AddSwaggerGen
services.AddSwaggerGen(options =>
{
options.SwaggerDoc("v1", new OpenApiInfo
{
Title = "接口文档",
Version = "v1",
Description = "测试 webapi"
});
// 遍历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 OpenApiInfo
{
Title = info?.Title,
Version = info?.Version,
Description = info?.Description
});
});
// 没有特性的接口分到NoGroup上
options.SwaggerDoc("NoGroup", new OpenApiInfo
{
Title = "无分组"
});
// 判断接口归于哪个分组
options.DocInclusionPredicate((docName, apiDescription) =>
{
if (docName == "NoGroup")
{
// 当分组为NoGroup时,只要没加特性的接口都属于这个组
return string.IsNullOrEmpty(apiDescription.GroupName);
}
else
{
return apiDescription.GroupName == docName;
}
});
});
6、修改 Configure 方法的 UseSwaggerUI
app.UseSwaggerUI(options =>
{
// 遍历ApiGroupNames所有枚举值生成接口文档
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", "无分组");
options.RoutePrefix = string.Empty;
});
自定义UI
前几天,前端同事和我吐槽,Swagger
的原生UI
太丑了,又不够直观,想找个接口还得一个个收缩展开,总之就是很难用。
- 不够直观
- 不方便查找
有了上面的两点需求何不自己实现一套UI
呢?(最终还是用了第三方现成的)
文章最开始有提到OpenAPI
对应的 json
内容,大家也可以在浏览器的控制台看看,swagger ui
的数据源都来自于一个叫 swagger.json
的文件,数据源都有了,根据数据源再做一套 UI
也就不是什么难事了。
1、准备一个美观的单页面(网上找的)
2、将单页面相关内容放到项目内(记得开启静态文件读取)
app.UseStaticFiles();
3、将单页面指定为 UI 页面。
app.UseSwaggerUI(options =>
{
options.IndexStream = () => GetType().Assembly.GetManifestResourceStream("h.swagger.Swagger.index.html");
});
4、在单页面内处理 swagger.json 数据源。
5、最终效果
Swagger UI
的功能还是比较多的,比如:详情、调试。如果想自己实现一套UI
要做的工作还很多。所以,拿来主义永不过时,最终我还是选择了第三方开源的项目:Knife4j
。
使用起来也是非常简单,先引用包:IGeekFan.AspNetCore.Knife4jUI
,然后在Startup.Configure
中将 app.UseSwaggerUI
替换为:
app.UseKnife4UI(c =>
{
c.RoutePrefix = string.Empty;
c.SwaggerEndpoint($"/swagger/v1/swagger.json", "h.swagger.webapi v1");
});
.NET Core基础篇之:集成Swagger文档与自定义Swagger UI的更多相关文章
- 利用typescript生成Swagger文档
项目地址:https://github.com/wz2cool/swagger-ts-doc demo代码地址:https://github.com/wz2cool/swagger-ts-doc-de ...
- Core + Vue 后台管理基础框架8——Swagger文档
1.前言 作为前后端分离的项目,或者说但凡涉及到对外服务的后端,一个自描述,跟代码实时同步的文档是极其重要的.说到这儿,想起了几年前在XX速运,每天写完代码,还要给APP团队更新文档的惨痛经历.给人家 ...
- SpringBoot系列:六、集成Swagger文档
本篇开始介绍Api文档Swagger的集成 一.引入maven依赖 <dependency> <groupId>io.springfox</groupId> < ...
- asp.net core web api 生成 swagger 文档
asp.net core web api 生成 swagger 文档 Intro 在前后端分离的开发模式下,文档就显得比较重要,哪个接口要传哪些参数,如果一两个接口还好,口头上直接沟通好就可以了,如果 ...
- Asp.Net Core基础篇之:白话管道中间件
在Asp.Net Core中,管道往往伴随着请求一起出现.客户端发起Http请求,服务端去响应这个请求,之间的过程都在管道内进行. 举一个生活中比较常见的例子:旅游景区. 我们都知道,有些景区大门离景 ...
- asp.net core 2.1 生成swagger文档
新建asp.netcore2.1 api项目 “WebApplication1” 在nuget管理器中添加对Swashbuckle.AspNetCore 3.0.0.Microsoft.AspNetC ...
- 使用.NET 6开发TodoList应用(27)——实现API的Swagger文档化
系列导航及源代码 使用.NET 6开发TodoList应用文章索引 需求 在日常开发中,我们需要给前端提供文档化的API接口定义,甚至需要模拟架设一个fake服务用来调试接口字段.或者对于后端开发人员 ...
- 使用 Swagger 文档化和定义 RESTful API
大部分 Web 应用程序都支持 RESTful API,但不同于 SOAP API——REST API 依赖于 HTTP 方法,缺少与 Web 服务描述语言(Web Services Descript ...
- Springboot 系列(十六)你真的了解 Swagger 文档吗?
前言 目前来说,在 Java 领域使用 Springboot 构建微服务是比较流行的,在构建微服务时,我们大多数会选择暴漏一个 REST API 以供调用.又或者公司采用前后端分离的开发模式,让前端和 ...
随机推荐
- configure: error: invalid variable name: `'
今天在交叉编译一个编解码库的时候,出现一个莫名其妙的报错,一直找不到原因,后来无意中删除了一个空格,才发现就是这个空格造成的错误. ./configure --host=arm-linux LDFLA ...
- linux 内核源代码情景分析——i386 的页式内存管理机制
可以看出,在页面目录中共有210 = 1024个目录项,每个目录项指向一个页面表,而在每个页面表中又共有1024个页面描述项. 由图看出来,从线性地址到物理地址的映射过程为: 1)从CR3取得页面目录 ...
- Oracle创建表、删除表、修改表、字段增删改 语句总结
创建表: create table 表名 ( 字段名1 字段类型 默认值 是否为空 , 字段名2 字段类型 默认值 是否为空, 字段名3 字段类型 默认值 是否为空, ...... ); 创建一个us ...
- Linux ps -ef 命令输出解释
UID: 程序拥有者PID:程序的 IDPPID:程序父级程序的 IDC: CPU 使用的百分比STIME: 程序的启动时间TTY: 登录终端TIME : 程序使用掉 CPU 的时间CMD: 下达的 ...
- Win10自动备份oracle数据库
1.环境 操作系统:win10 数据库: 2.创建backup.bat文件 [ @echo offset name=%date:~0,4%%date:~5,2%%date:~8,2%set backu ...
- SpringCloud微服务实战——搭建企业级开发框架(十四):集成Sentinel高可用流量管理框架【限流】
Sentinel 是面向分布式服务架构的高可用流量防护组件,主要以流量为切入点,从限流.流量整形.熔断降级.系统负载保护.热点防护等多个维度来帮助开发者保障微服务的稳定性. Sentinel 具有 ...
- 【Go语言学习笔记】Go语言的基础语法
上一篇已经说了,Go的语法和C的很接近,直接看看异同即可. 变量 变量名还是一样,字母或下划线开头,区分大小写.不能是关键字. Go定义了int32和int64这种类型来显示声明大小,和C里面的sho ...
- css--元素居中常用方法总结
前言 元素居中是日常开发和学习中最常见的问题,同时也是面试中经常考察的知识点,本文来总结一下这方面的知识点. 正文 1.水平居中 (1)子父元素宽度固定,子元素设置 margin:auto,并且子元素 ...
- [hdu6145]Arithmetic of Bomb II
对于题中的"normal expression"(仅含加减乘和无前导0的非负整数,无括号)的计算,实际上并不需要通常的表达式求值,而可以用下述方式计算-- 维护三元组$(a,b,c ...
- [bzoj1082]栅栏
先二分答案,然后搜索暴力判断由于数据范围较大,需要剪枝:1.当前所有可能被用到的木板长度和(长度要不小于最小所需长度)>=所要拼成的所有木板的和:2.对于需求从大到小枚举木板(这样一开始枚举次数 ...