使⽤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。具体效果如下图所示:

Swagger2依赖

在 pom.xml 中加⼊Swagger2的依赖

<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 。

package com.kingram.springboot.config;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import springfox.documentation.builders.ApiInfoBuilder;
import springfox.documentation.builders.PathSelectors;
import springfox.documentation.builders.RequestHandlerSelectors;
import springfox.documentation.service.ApiInfo;
import springfox.documentation.spi.DocumentationType;
import springfox.documentation.spring.web.plugins.Docket;
import pringfox.documentation.swagger2.annotations.EnableSwagger2; @Configuration
@EnableSwagger2
public class Swagger2 {    @Bean   
public Docket createRestApi() {       
return new Docket(DocumentationType.SWAGGER_2)               
.apiInfo(apiInfo()) .select()               
.apis(RequestHandlerSelectors               
.basePackage("com.kingram.springboot"))               
.paths(PathSelectors.any()) .build();   
}    private ApiInfo apiInfo() {       
return new ApiInfoBuilder()               
.title("Spring Boot中使⽤Swagger2构建RESTful APIs")               
.description("swagger2使用范例")               
.termsOfServiceUrl("https://www.cnblogs.com/Kingram/")            
.contact("Kingram")               
.version("1.0")               
.build();   
}
}

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

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

添加⽂档内容

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

@RestController
@RequestMapping(value = "/users")
public class UserController {   
// 创建线程安全的Map   
private static Map<Long, User> users = Collections.synchronizedMap(new HashMap<>());    @ApiOperation(value="获取⽤户列表", notes="")
@RequestMapping(value = "/", method = RequestMethod.GET)   
public List<User> getUserList() {          
List<User> r = new ArrayList<>(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(@ModelAttribute 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, @ModelAttribute 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的描述信息,如下图所示。

⽂档访问与调试

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

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

相⽐为这些接⼝编写⽂档的⼯作,我们增加的配置内容是⾮常少⽽且精简的,对于原有代码的侵⼊也在忍受范围之内。因此,在构建RESTful API的同时,加⼊swagger来对API⽂档进⾏管理,是个不错的选择。

本文转自

使⽤Swagger2构建强⼤的RESTful API⽂档的更多相关文章

  1. SpringBoot_06_使用Swagger2构建强大的RESTful API文档

    二.参考资料 1.Spring Boot中使用Swagger2构建强大的RESTful API文档 2.

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

    由于Spring Boot能够快速开发.便捷部署等特性,相信有很大一部分Spring Boot的用户会用来构建RESTful API.而我们构建RESTful API的目的通常都是由于多终端的原因,这 ...

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

    项目现状:由于前后端分离,没有很好的前后端合作工具. 由于接口众多,并且细节复杂(需要考虑不同的HTTP请求类型.HTTP头部信息.HTTP请求内容等),高质量地创建这份文档本身就是件非常吃力的事,下 ...

  4. 使用Swagger2构建强大的RESTful API文档(2)(二十三)

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

  5. 使用Swagger2构建强大的RESTful API文档(1)(二十二)

    由于Spring Boot能够快速开发.便捷部署等特性,相信有很大一部分Spring Boot的用户会用来构建RESTful API.而我们构建RESTful API的目的通常都是由于多终端的原因,这 ...

  6. Spring Boot教程(二十三)使用Swagger2构建强大的RESTful API文档(2)

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

  7. Spring Boot教程(二十二)使用Swagger2构建强大的RESTful API文档(1)

    由于Spring Boot能够快速开发.便捷部署等特性,相信有很大一部分Spring Boot的用户会用来构建RESTful API.而我们构建RESTful API的目的通常都是由于多终端的原因,这 ...

  8. 集成 Swagger2 构建强大的 RESTful API 文档

    微信公众号:一个优秀的废人如有问题或建议,请后台留言,我会尽力解决你的问题. 前言 快过年了,不知道你们啥时候放年假,忙不忙.反正我是挺闲的,所以有时间写 blog.今天给你们带来 SpringBoo ...

  9. Spring Boot2 系列教程 (四) | 集成 Swagger2 构建强大的 RESTful API 文档

    前言 快过年了,不知道你们啥时候放年假,忙不忙.反正我是挺闲的,所以有时间写 blog.今天给你们带来 SpringBoot 集成 Swagger2 的教程. 什么是 Swagger2 Swagger ...

随机推荐

  1. [bug] Flask css 不更新

    参考 https://blog.csdn.net/weixin_30454481/article/details/97108510

  2. Docker——Registry搭建私有镜像仓库

    前言 在 Docker 中,当我们执行 docker pull xxx 的时候,它实际上是从 registry.hub.docker.com 这个地址去查找,这就是Docker公司为我们提供的公共仓库 ...

  3. TrueCrypt与CryptSetup双系统全盘加密(图文)

    http://blog.topsec.com.cn/truecrypt%E4%B8%8Ecryptsetup%E5%8F%8C%E7%B3%BB%E7%BB%9F%E5%85%A8%E7%9B%98% ...

  4. 二进制部署K8S-1基本概念

    二进制部署K8S-1基本概念 感谢老男孩教育王导的公开视频,文档整理自https://www.yuque.com/duduniao/k8s. 1.实验环境 1.1 虚拟机 因为在后期运行容器需要有大量 ...

  5. commit信息修改

    场景:向社区提交commit信息,code reviewer给你回复说,请添加TrivialFix并且完善commit信息.好吧,虽然这对代码的运行无关紧要,但是对于日后的代码管理是很有必要的. 解决 ...

  6. HAProxy之三----keepalived配合脚本对HAProxy、ping网关实现高可用检测

    调用脚本参数含义 vrrp_script<SCRIPT_NAME> { #定义一个检测脚本,在global_defs之外配置 script <STRING>|<QUOTE ...

  7. 3.21-22 od、tee

    3.21 od:按不同进制显示文件       od命令用于输出文件的八进制.十六进制或者其他格式编码的字节,通常用于显示或查看文件中不能直接显示在终端的字符.   -A 地址进制    按指定的进制 ...

  8. Docker学习(13) Docker容器的网络连接

    Docker容器的网络连接 Docker容器的网络基础 先安装网桥管理工具 Docker容器的互联 默认 Docker容器与外部网络的连接

  9. Processing平台之PVector求角度

    问题:在processing 平台,通过给定三个PVector向量,如何求他们之间的夹角,同时确定是在左侧还是右侧? 如图所示,在processing 平台中,PVector表示点的坐标是以原点为起点 ...

  10. CVPR2019论文解读:单眼提升2D检测到6D姿势和度量形状

    CVPR2019论文解读:单眼提升2D检测到6D姿势和度量形状 ROI-10D: Monocular Lifting of 2D Detection to 6D Pose and Metric Sha ...