Swagger2简介
由于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=
下面来具体介绍,如果在Spring Boot中使用Swagger2。首先,我们需要一个Spring Boot实现的RESTful API工程,若您没有做过这类内容,建议先阅读
Spring Boot构建一个较为复杂的RESTful APIs和单元测试。
下面的内容我们会以教程样例中的Chapter3-1-1进行下面的实验(Chpater3-1-5是我们的结果工程,亦可参考)。
添加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。
@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注解来给参数增加说明。
@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的描述信息,如下图所示。
alt
API文档访问与调试
在上图请求的页面中,我们看到user的Value是个输入框?是的,Swagger除了查看接口功能外,还提供了调试测试功能,我们可以点击上图中右侧的Model Schema(黄色区域:它指明了User的数据结构),此时Value中就有了user对象的模板,我们只需要稍适修改,点击下方“Try it out!”按钮,即可完成了一次请求调用!
此时,你也可以通过几个GET请求来验证之前的POST请求是否正确。
相比为这些接口编写文档的工作,我们增加的配置内容是非常少而且精简的,对于原有代码的侵入也在忍受范围之内。因此,在构建RESTful API的同时,加入swagger来对API文档进行管理,是个不错的选择。
参考信息
Swagger官方网站
Swagger2简介相关推荐
- Swagger2简介及入门案例
Swagger2 1 Swagger2概念 Swagger 是一款RESTFUL接口的.基于YAML.JSON语言的文档在线自动生成.代码自动生成的工具. 2 Swagger2入门案例 1 在spri ...
- SpringBoot2.0 整合 Swagger2 ,构建接口管理界面
一.Swagger2简介 1.Swagger2优点 整合到Spring Boot中,构建强大RESTful API文档.省去接口文档管理工作,修改代码,自动更新,Swagger2也提供了强大的页面测试 ...
- Swagger2 总结
Swagger 2 总结 目录 Swagger 2 总结 一.Swagger 简介 1. 前言 2. Open API 是什么 3. Swagger2 简介 4. 官网 二.Springfox 三.S ...
- Swagger2常用注解说明
文章目录 Swagger2简介 使用Swagger解决的问题 Spring Boot集成Swagger2 添加依赖 添加Swagger2Config配置类 编写接口 用户DTO 用户controlle ...
- Swagger 学习笔记 | Swagger 简介 | Springfox 简介 | Springfox 2.9.2 常用注解 | Spring Boot 整合 Swagger2 案例
文章目录 一.Swagger 简介 二.Springfox 简介 三.Springfox2.9.2 常用注解 四.SpringBoot 整合 Swagger2 4.1 引入Maven依赖 4.2 项目 ...
- SpringBoot+Mybatis+Swagger2环境搭建
点击上方"方志朋",选择"设为星标" 回复"666"获取新整理的面试资料 作者:calebman https://www.jianshu.c ...
- 03、Swagger2和Springmvc整合详细记录(爬坑记录)
时间 内容 备注 2018年6月18日 基本使用 spirngmvc整合swagger2 开始之前这个系列博文基本是,在项目的使用中一些模块的内容记录,但是后期逐渐优化,不单单是整合内容. swagg ...
- freemarker使用说明_SpringBoot+Swagger2集成详细说明
SpringBoot+Swagger2集成详细说明 引言: 为什么使用Swagger? 在Vue没有出来之前,都是前后端在一起: 后端用的SSM或者SSH框架 前端完全就是静态页面+模板引擎.例如:J ...
- SpringBoot2.x整合Swagger2 实现API文档实时生成
我们提供Restful接口的时候,API文档是尤为的重要,它承载着对接口的定义,描述等,本文主要介绍了SpringBoot集成Swagger2生成接口文档的方法示例,需要的朋友们下面随着小编来一起学习 ...
最新文章
- python按行读取txt文件-Python逐行读取txt文本,按符合分割词并逐行写入txt
- 51单片机串口通信(字符串接收和发送)
- 01_[pathlib]内置pathlib库的常用属性和方法
- linux apache添加多站点配置(Ubuntn和Centos)
- SAP UI5 应用开发教程之六十二 - 基于 OData V4 的 SAP UI5 表格控件使用方法介绍
- [Linux]Centos 6.3 下源代码安装gcc 4.8.2/4.9.2
- 算法描述怎么写_管件材料描述怎么写
- 数据访问基础类(基于Access数据库)
- 基于JAVA+SpringMVC+Mybatis+MYSQL的校园餐厅系统
- 数据湖存储格式Hudi原理与实践
- vue package.json 解析
- 单片机百位计数c语言,单片机c语言版数管动态显示实验报告.doc
- 基于51单片机的智能窗口控制系统(protues仿真+程序+论文+PPT+PCB)
- 双摄像头另一个有什么用_手机双摄像头为什么有前后和后双两种?各有什么用?...
- dnw驱动更新,支持全系统(xp,win7,win8/win10)
- 《Pro SQL Server Internals, 2nd edition》节选翻译(一)
- ie浏览器flash player不能用的解决方案
- JSON文件的读取操作详解
- 2018双一流排名 计算机,哪些双一流学科进入软科“2018中国最好学科排名”
- hive的搭建及其入门一
热门文章
- Mysql数据库的详细安装步骤
- 熟悉Minix3.1.2a操作系统的进程管理
- 苏州企业申报高新技术企业的工作流程
- 怎么查2020计算机准考证号,2020考研准考证号忘了怎么办?查询方式有哪些?
- ENVI自带地物波谱库文件说明和查看(以ENVI5.3为例)
- Fiddler抓包工具简介,安装及使用教程详解
- css动态彩虹背景,59.纯 CSS 创作彩虹背景文字
- “4.29”赛事再燃“360春秋杯”国际挑战赛报名启动
- ros与arduino通信控制直流电机
- 中职计算机专业英语课程改革初探,计算机专业英语教学改革初探