Spring Boot 中使用 Swagger2 构建强大的 RESTful API 文档
项目现状:由于前后端分离,没有很好的前后端合作工具。
由于接口众多,并且细节复杂(需要考虑不同的HTTP请求类型、HTTP头部信息、HTTP请求内容等),高质量地创建这份文档本身就是件非常吃力的事,下游的抱怨声不绝于耳。
随着时间推移,不断修改接口实现的时候都必须同步修改接口文档,而文档与代码又处于两个不同的媒介,除非有严格的管理机制,不然很容易导致不一致现象。
为了解决上面这样的问题,本文将介绍RESTful API的重磅好伙伴Swagger2,它可以轻松的整合到Spring Boot中,并与Spring MVC程序配合组织出强大RESTful API文档。它既可以减少我们创建文档的工作量,同时说明内容又整合入实现代码中,让维护文档和修改代码整合为一体,可以让我们在修改代码逻辑的同时方便的修改文档说明。另外Swagger2也提供了强大的页面测试功能来调试每个RESTful API。
添加Swagger2依赖
在pom.xml中加入Swagger2的依赖
1
2
3
4
5
6
7
8
9
10
|
<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
|
@Configuration @EnableSwagger2 public class Swagger2 { @Bean public Docket createRestApi() { return new Docket(DocumentationType.SWAGGER_2) .apiInfo(apiInfo()) .select() .apis(RequestHandlerSelectors.basePackage(
" )) .paths(PathSelectors.any()) .build(); } private ApiInfo apiInfo() { return new ApiInfoBuilder() .title( "Spring Boot中使用Swagger2构建RESTful APIs" ) .description( "更多Spring Boot相关文章请关注:swagger官网" ) .termsOfServiceUrl( "https://swagger.io/" ) .contact( "程序猿DD" ) .version( "1.0" ) .build(); } } |
如上代码所示,通过@Configuration注解,让Spring来加载该类配置。再通过@EnableSwagger2注解来启用Swagger2。
测试代码:
package com.bai.controller; import com.bai.domain.User;
import io.swagger.annotations.ApiImplicitParam;
import io.swagger.annotations.ApiImplicitParams;
import io.swagger.annotations.ApiOperation;
import org.springframework.web.bind.annotation.*; import java.util.*; /**
* Created by DELL on 2017/7/5.
*/
@RestController
@RequestMapping(value = "/users") // 通过这里配置使下面的映射都在/users下,可去除
public class UsersController {
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, paramType = "path", 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, paramType = "path", 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.setUserName(user.getUserName());
u.setEmail(user.getEmail());
users.put(id, u);
return "success";
} @ApiOperation(value = "删除用户", notes = "根据url的id来指定删除对象")
@ApiImplicitParam(name = "id", value = "用户ID", required = true,paramType="path", 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的页面。
Spring Boot 中使用 Swagger2 构建强大的 RESTful API 文档的更多相关文章
- Spring Boot中使用Swagger2构建强大的RESTful API文档
由于Spring Boot能够快速开发.便捷部署等特性,相信有很大一部分Spring Boot的用户会用来构建RESTful API.而我们构建RESTful API的目的通常都是由于多终端的原因,这 ...
- SpringBoot_06_使用Swagger2构建强大的RESTful API文档
二.参考资料 1.Spring Boot中使用Swagger2构建强大的RESTful API文档 2.
- Spring Boot教程(二十二)使用Swagger2构建强大的RESTful API文档(1)
由于Spring Boot能够快速开发.便捷部署等特性,相信有很大一部分Spring Boot的用户会用来构建RESTful API.而我们构建RESTful API的目的通常都是由于多终端的原因,这 ...
- 使用Swagger2构建强大的RESTful API文档(1)(二十二)
由于Spring Boot能够快速开发.便捷部署等特性,相信有很大一部分Spring Boot的用户会用来构建RESTful API.而我们构建RESTful API的目的通常都是由于多终端的原因,这 ...
- Spring Boot教程(二十三)使用Swagger2构建强大的RESTful API文档(2)
添加文档内容 在完成了上述配置后,其实已经可以生产文档内容,但是这样的文档主要针对请求本身,而描述主要来源于函数等命名产生,对用户并不友好,我们通常需要自己增加一些说明来丰富文档内容.如下所示,我们通 ...
- Spring Boot2 系列教程 (四) | 集成 Swagger2 构建强大的 RESTful API 文档
前言 快过年了,不知道你们啥时候放年假,忙不忙.反正我是挺闲的,所以有时间写 blog.今天给你们带来 SpringBoot 集成 Swagger2 的教程. 什么是 Swagger2 Swagger ...
- 集成 Swagger2 构建强大的 RESTful API 文档
微信公众号:一个优秀的废人如有问题或建议,请后台留言,我会尽力解决你的问题. 前言 快过年了,不知道你们啥时候放年假,忙不忙.反正我是挺闲的,所以有时间写 blog.今天给你们带来 SpringBoo ...
- 使用Swagger2构建强大的RESTful API文档(2)(二十三)
添加文档内容 在完成了上述配置后,其实已经可以生产文档内容,但是这样的文档主要针对请求本身,而描述主要来源于函数等命名产生,对用户并不友好,我们通常需要自己增加一些说明来丰富文档内容.如下所示,我们通 ...
- Spring Boot中使用Swagger2构建强大的RESTful(最新全,无坑)
1:说明 网上这类文章 太多, 一搜一大把 ,但是要不是知识太过于老旧,就是配置没有说名清楚,你的项目按照他的配置却不能正常运行: 所以本文的目的: 配置swagger 2 那swagger 1 不 ...
随机推荐
- 【收藏】常用SQL语句
.1参考手册 ), owner ), species ), sex ), birth DATE, death DATE); //创建表 mysql> show tables; //查看数据库中的 ...
- java常见数据结构整理
java中容器类数据结构主要在java.util包中. java.util包中三个重要的接口及特点:List(列表).Set(保证集合中元素唯一).Map(维护多个key-value键值对,保证key ...
- CAP理论中, P(partition tolerance, 分区容错性)的合理解释
在CAP理论中, 对partition tolerance分区容错性的解释一般指的是分布式网络中部分网络不可用时, 系统依然正常对外提供服务, 而传统的系统设计中往往将这个放在最后一位. 这篇文章对这 ...
- 【laravel5.4】安装predis
1.服务器先安装redis-server,这是毋庸置疑的!!! 2.服务器开启redis-server,配置相关参数 3.laravel执行 : $ yourPhpPath composer.pha ...
- [SQL Server]从 varchar 数据类型到 datetime 数据类型的转换产生一个超出范围的值。
见下图sql, 使用dateadd()转换时报如题错误, 原因是数据库表中存入的数据格式不正确, 数据格式不正确, 数据格式不正确, 重要的事情讲3遍!! ca.batch_no的前8位必须是日 ...
- 获取当前日期 java
SimpleDateFormat smpDateFormat = new SimpleDateFormat("yyyy-MM-dd HH:mm:ss"); SimpleDateFo ...
- 谈UIView Animation编程艺术
一.大小动画(改变frame) -(void)changeFrame{ CGRect originalRect = self.anView.frame; CGRect rect = CGRectMak ...
- iOS绘图UIBezierPath 和 Core Graphics框架
前言 iOS系统本身提供了两套绘图的框架,即UIBezierPath 和 Core Graphics.而前者所属UIKit,其实是对Core Graphics框架关于path的进一步封装,所以使用起来 ...
- 最新的 CocoaPods 的使用教程(一)
发布开源库到CocoaPods的时候.对CocoaPods重新学习了一下. 1.CocoaPods的日常使用 2.创建CocoaPods的私有库 3.创建CocoaPods的开源库 一. CocoaP ...
- 新浪安装weiphp2.0的方法
请安装此网页的方法来安装: https://coding.net/u/idoubi666/p/weiphp-sae/git