Spring Boot中使用Swagger2构建强大的RESTful API文档

由于Spring Boot能够快速开发、便捷部署等特性,相信有很大一部分Spring Boot的用户会用来构建RESTful API。而我们构建RESTful API的目的通常都是由于多终端的原因,这些终端会共用很多底层业务逻辑,因此我们会抽象出这样一层来同时服务于多个移动端或者Web前端。

这样一来,我们的RESTful API就有可能要面对多个开发人员或多个开发团队:IOS开发、Android开发或是Web开发等。为了减少与其他团队平时开发期间的频繁沟通成本,传统做法我们会创建一份RESTful API文档来记录所有接口细节,然而这样的做法有以下几个问题:

  • 由于接口众多,并且细节复杂(需要考虑不同的HTTP请求类型、HTTP头部信息、HTTP请求内容等),高质量地创建这份文档本身就是件非常吃力的事,下游的抱怨声不绝于耳。
  • 随着时间推移,不断修改接口实现的时候都必须同步修改接口文档,而文档与代码又处于两个不同的媒介,除非有严格的管理机制,不然很容易导致不一致现象。

为了解决上面这样的问题,本文将介绍RESTful API的重磅好伙伴Swagger2,它可以轻松的整合到Spring Boot中,并与Spring MVC程序配合组织出强大RESTful API文档。它既可以减少我们创建文档的工作量,同时说明内容又整合入实现代码中,让维护文档和修改代码整合为一体,可以让我们在修改代码逻辑的同时方便的修改文档说明。另外Swagger2也提供了强大的页面测试功能来调试每个RESTful API。具体效果如下图所示:

alt=alt=

下面来具体介绍,如果在Spring Boot中使用Swagger2。首先,我们需要一个Spring Boot实现的RESTful API工程,若您没有做过这类内容,建议先阅读
Spring Boot构建一个较为复杂的RESTful APIs和单元测试。

下面的内容我们会以教程样例中的Chapter3-1-1进行下面的实验(Chpater3-1-5是我们的结果工程,亦可参考)。

添加Swagger2依赖

pom.xml中加入Swagger2的依赖

1
2
3
4
5
6
7
8
9
10
11
<dependency>
<groupId>io.springfox</groupId>
<artifactId>springfox-swagger2</artifactId>
<version>2.2.2</version>
</dependency>
<dependency>
<groupId>io.springfox</groupId>
<artifactId>springfox-swagger-ui</artifactId>
<version>2.2.2</version>
</dependency>

创建Swagger2配置类

Application.java同级创建Swagger2的配置类Swagger2

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
@Configuration
@EnableSwagger2
public class Swagger2 {
@Bean
public Docket createRestApi() {
return new Docket(DocumentationType.SWAGGER_2)
.apiInfo(apiInfo())
.select()
.apis(RequestHandlerSelectors.basePackage("com.didispace.web"))
.paths(PathSelectors.any())
.build();
}
private ApiInfo apiInfo() {
return new ApiInfoBuilder()
.title("Spring Boot中使用Swagger2构建RESTful APIs")
.description("更多Spring Boot相关文章请关注:http://blog.didispace.com/")
.termsOfServiceUrl("http://blog.didispace.com/")
.contact("程序猿DD")
.version("1.0")
.build();
}
}

如上代码所示,通过@Configuration注解,让Spring来加载该类配置。再通过@EnableSwagger2注解来启用Swagger2。

再通过createRestApi函数创建Docket的Bean之后,apiInfo()用来创建该Api的基本信息(这些基本信息会展现在文档页面中)。select()函数返回一个ApiSelectorBuilder实例用来控制哪些接口暴露给Swagger来展现,本例采用指定扫描的包路径来定义,Swagger会扫描该包下所有Controller定义的API,并产生文档内容(除了被@ApiIgnore指定的请求)。

添加文档内容

在完成了上述配置后,其实已经可以生产文档内容,但是这样的文档主要针对请求本身,而描述主要来源于函数等命名产生,对用户并不友好,我们通常需要自己增加一些说明来丰富文档内容。如下所示,我们通过@ApiOperation注解来给API增加说明、通过@ApiImplicitParams@ApiImplicitParam注解来给参数增加说明。

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
@RestController
@RequestMapping(value="/users") // 通过这里配置使下面的映射都在/users下,可去除
public class UserController {
static Map<Long, User> users = Collections.synchronizedMap(new HashMap<Long, User>());
@ApiOperation(value="获取用户列表", notes="")
@RequestMapping(value={""}, method=RequestMethod.GET)
public List<User> getUserList() {
List<User> r = new ArrayList<User>(users.values());
return r;
}
@ApiOperation(value="创建用户", notes="根据User对象创建用户")
@ApiImplicitParam(name = "user", value = "用户详细实体user", required = true, dataType = "User")
@RequestMapping(value="", method=RequestMethod.POST)
public String postUser(@RequestBody User user) {
users.put(user.getId(), user);
return "success";
}
@ApiOperation(value="获取用户详细信息", notes="根据url的id来获取用户详细信息")
@ApiImplicitParam(name = "id", value = "用户ID", required = true, dataType = "Long")
@RequestMapping(value="/{id}", method=RequestMethod.GET)
public User getUser(@PathVariable Long id) {
return users.get(id);
}
@ApiOperation(value="更新用户详细信息", notes="根据url的id来指定更新对象,并根据传过来的user信息来更新用户详细信息")
@ApiImplicitParams({
@ApiImplicitParam(name = "id", value = "用户ID", required = true, dataType = "Long"),
@ApiImplicitParam(name = "user", value = "用户详细实体user", required = true, dataType = "User")
})
@RequestMapping(value="/{id}", method=RequestMethod.PUT)
public String putUser(@PathVariable Long id, @RequestBody User user) {
User u = users.get(id);
u.setName(user.getName());
u.setAge(user.getAge());
users.put(id, u);
return "success";
}
@ApiOperation(value="删除用户", notes="根据url的id来指定删除对象")
@ApiImplicitParam(name = "id", value = "用户ID", required = true, dataType = "Long")
@RequestMapping(value="/{id}", method=RequestMethod.DELETE)
public String deleteUser(@PathVariable Long id) {
users.remove(id);
return "success";
}
}

完成上述代码添加上,启动Spring Boot程序,访问:http://localhost:8080/swagger-ui.html
。就能看到前文所展示的RESTful API的页面。我们可以再点开具体的API请求,以POST类型的/users请求为例,可找到上述代码中我们配置的Notes信息以及参数user的描述信息,如下图所示。

altalt

API文档访问与调试

在上图请求的页面中,我们看到user的Value是个输入框?是的,Swagger除了查看接口功能外,还提供了调试测试功能,我们可以点击上图中右侧的Model Schema(黄色区域:它指明了User的数据结构),此时Value中就有了user对象的模板,我们只需要稍适修改,点击下方“Try it out!”按钮,即可完成了一次请求调用!

此时,你也可以通过几个GET请求来验证之前的POST请求是否正确。

相比为这些接口编写文档的工作,我们增加的配置内容是非常少而且精简的,对于原有代码的侵入也在忍受范围之内。因此,在构建RESTful API的同时,加入swagger来对API文档进行管理,是个不错的选择。

转载于:https://www.cnblogs.com/xiangjune/p/6639832.html

本文来自互联网用户投稿,该文观点仅代表作者本人,不代表本站立场。本站仅提供信息存储空间服务,不拥有所有权,不承担相关法律责任。如若转载,请注明出处:http://www.mzph.cn/news/401274.shtml

如若内容造成侵权/违法违规/事实不符,请联系多彩编程网进行投诉反馈email:809451989@qq.com,一经查实,立即删除!

相关文章

关于公司没有公网IP也没有动态IP,如何远程办公呢?

2019独角兽企业重金招聘Python工程师标准>>> 迫于公司网络环境特殊&#xff0c;没有公网IP地址&#xff0c;也没有动态IP地址&#xff0c;其实就是园区分了一根内网固定IP的网线过来&#xff0c;这两天正巧有同事要外出办公&#xff0c;问题来了&#xff0c;开发环境…

数据库安全

先分3点从全局来看 对操作系统的安全需求:防止对DBMS的非法访问和修改,保护存储的数据、文件的安全性,对数据库用户的认证 对数据库系统本身的安全需求:用户认证管理、访问控制、审计,数据库的稳定性,保证数据的安全性与完整性&#xff0c;完善的恢复功能,数据加密 对数据库应用…

ST_LINK/V2 SWIM和SWD、JTAG下载口说明

LED状态说明 闪烁红色&#xff1a;ST-LINK/V2连接到计算机后&#xff0c;第一次USB枚举过程红色&#xff1a;ST-LINK/V2与计算机已建立连接闪烁绿色/红色&#xff1a;目标板和计算机在进行数据交换绿色&#xff1a;通讯完成橙色&#xff08;红色绿色&#xff09;&#xff1a;通…

js 日期扩展

// 对Date的扩展&#xff0c;将 Date 转化为指定格式的String // 月(M)、日(d)、小时(h)、分(m)、秒(s)、季度(q) 可以用 1-2 个占位符&#xff0c; // 年(y)可以用 1-4 个占位符&#xff0c;毫秒(S)只能用 1 个占位符(是 1-3 位的数字) // 例子&#xff1a; // (new Date()…

Gerrit的用法及与gitlab的区别

Python微信订餐小程序课程视频 https://edu.csdn.net/course/detail/36074 Python实战量化交易理财系统 https://edu.csdn.net/course/detail/35475 来到一个新的团队&#xff0c;开发的代码被同事覆盖了。找同事核实&#xff0c;同事却说根本没有看到我的代码。经过一番沟通…

人事资料

考察人品 1&#xff0e; 你有缺点吗 2&#xff0e; 当你发现你的顶头上司用办公电话聊私事&#xff0c;你会怎么做 3&#xff0e; 作为财务经理&#xff0c;如果总经理要求你在一年之内逃税100万&#xff0c;你会怎么做 4&#xff0e; 你的耳环多少钱买的 考察能力 1&#…

c语言位段

通常计算机最小处理单元基本就是byte字节了&#xff0c;就是八个二进制位&#xff0c;位段则是按计算机中真正的最小单位二进制位来存储处理数据&#xff0c;可以更高效的利用内存。 位段(bit-field)是以位为单位来定义结构体(或联合体)中的成员变量所占的空间。含有位段的结构…

The 15th UESTC Programming Contest Preliminary H - Hesty Str1ng cdoj1551

地址&#xff1a;http://acm.uestc.edu.cn/#/problem/show/1551 题目&#xff1a; Hesty Str1ng Time Limit: 3000/1000MS (Java/Others) Memory Limit: 65535/65535KB (Java/Others) A chrysanthemum was painted on the second page, and we tried to use the magic pow…

python基础之序列类型的方法——列表元组

Python微信订餐小程序课程视频 https://edu.csdn.net/course/detail/36074 Python实战量化交易理财系统 https://edu.csdn.net/course/detail/35475 Hello大家好&#xff0c;我是python学习者小杨同学&#xff0c;上次跟大家分享关于python的数值类型和序列类型&#xff0c;…

北方网-ios预科班

http://www.tudou.com/listplay/9oNp8KgmJZw.html 转载于:https://www.cnblogs.com/freeliver54/archive/2012/09/16/2687189.html

管家婆SQL SERVER数据库“可能发生了架构损坏。请运行DBCC CHECKCATALOG”修复

【数据库故障描述】用户在使用过过程中&#xff0c;由于突然断电&#xff0c;造成数据无法读取。DBCC检测数据库提示以下错误消息211&#xff0c;级别23&#xff0c;状态51&#xff0c;第1 行可能发生了架构损坏。请运行DBCC CHECKCATALOG。消息0&#xff0c;级别20&#xff0c…

1009 产生数 2002年NOIP全国联赛普及组

009 产生数 2002年NOIP全国联赛普及组 时间限制: 1 s 空间限制: 128000 KB 题目等级 : 黄金 Gold 题目描述 Description给出一个整数 n&#xff08;n<10^30) 和 k 个变换规则&#xff08;k<15&#xff09;。  规则&#xff1a;   一位数可变换成另一个一位数&#…

K近邻算法

Python微信订餐小程序课程视频 https://edu.csdn.net/course/detail/36074 Python实战量化交易理财系统 https://edu.csdn.net/course/detail/35475 一、K近邻算法简介 K近邻算法(K-Nearest Neighbor)简称KNN算法,是最简单的预测模型之一&#xff0c;它没有多少数学上的假设…

easyui 点滴记录

为什么80%的码农都做不了架构师&#xff1f;>>> 【1.安装】&#xff1a;pip install easygui 【2.常用】 integerbox 交互式输入数字textbox 交互式输入文本ccbox 确认判断boolbox 是否判断multchoicebox 多选条目choicebox 单选条目buttonbox 单选按钮【3.体验一…

如何在邮件系统中使用自己的域名?

如何在邮件系统中使用自己的域名&#xff1f; 主要分为以下两种情况&#xff1a;1.MX记录已经存在&#xff1a; 如果MX记录已经存在&#xff0c;并且已经检查出是在某一个域名服务器上&#xff0c;您需要做的工作就是与您的域名服务商或该域名服务器的管理人员联系&#xff0c;…

IAR切BANK--BANK说明

一、为什么要用到BANK&#xff1f; C51单片机的最大寻址范围为2^1664K&#xff0c;为了突破64K代码的限制&#xff0c;就需要采用C51的切BANK。 二、切BANK的原理 代码地址空间的上半部 ,以重叠BANK0的物理地址空间 , 硬件设计了 n个存储 器页面来存储程序代码 。在任一时刻 …

pl/sql developer 自带汉化选项

pl/sql developer 自带汉化选项 版本&#xff1a;11.0.2 工具 -> 选项 -> 用户界面 ->外观&#xff0c; 第一项就是选择语言&#xff1b; 选择Chinese.lang&#xff0c;如果有的话&#xff1b; 转载于:https://www.cnblogs.com/stono/p/6645548.html

实现自己的BeanFactory、AOP以及声明式事务

实现自己的BeanFactory 在使用spring时&#xff0c;我们很少用"new"关键字创建对象&#xff0c;而是通过spring容器BeanFactory提供的getBean()方法得到对象&#xff1a; BeanFactory ctx new C…

Docker遇到的一些问题和感想

Python微信订餐小程序课程视频 https://edu.csdn.net/course/detail/36074 Python实战量化交易理财系统 https://edu.csdn.net/course/detail/35475 Docker 是“不可变”架构。 当你希望改变一个服务的时候&#xff08;比如更新版本、修改配置、开放端口&#xff09;&#…

hdu 4293 Groups DP

http://acm.hdu.edu.cn/showproblem.php?pid4293 题意&#xff1a; 有n个人分成了若干组走在一条林荫道路上&#xff0c;导游为了能够确定人数&#xff0c;要求每个人喊出自己所在的队伍前边有多少人Ai表示,后边有多少人Bi表示&#xff0c;于是我们得到了n条信息。这里面有错误…