本文将介绍RESTful API可视化调试工具Swagger2,它可以轻松的整合到spring生态链中,并与Spring MVC程序配合组织出强大RESTful API文档。它既可以减少我们创建文档的工作量,同时又将说明内容整合入实现代码中,让维护文档和修改代码整合为一体,方便让我们在修改代码逻辑的同时方便的修改文档说明。另外Swagger2也提供了强大的页面测试功能来调试每个RESTful API,具体效果如下图所示:
Spring Boot整合Swagger2
1、添加Swagger2依赖
在pom.xml中加入Swagger2的依赖
<!--swagger2-->
<dependency>
<groupId>io.springfox</groupId>
<artifactId>springfox-swagger2</artifactId>
<version>2.6.1</version>
</dependency>
<dependency>
<groupId>io.springfox</groupId>
<artifactId>springfox-swagger-ui</artifactId>
<version>2.6.1</version>
</dependency>
2、编写Swagger2配置类
类名随意,但需要增加@EnableSwagger2和@Configuration注解,如下:
package cn.no7player.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.service.Contact;
import springfox.documentation.spi.DocumentationType;
import springfox.documentation.spring.web.plugins.Docket;
import springfox.documentation.swagger2.annotations.EnableSwagger2;
/**
*
* ClassName: Swagger2Config <br/>
* Function: TODO ADD FUNCTION. <br/>
* Reason: TODO ADD REASON(可选). <br/>
* date: 2017年4月13日 下午5:19:22 <br/>
*
* @author lichch
* @version
* @since JDK 1.7
*/
@EnableSwagger2
@Configuration
public class Swagger2Config {
@Bean
public Docket createRestApi() {
return new Docket(DocumentationType.SWAGGER_2).apiInfo(apiInfo()).select()
// 为当前包路径cn.no7player.controller
.apis(RequestHandlerSelectors.basePackage("cn.no7player.controller")).paths(PathSelectors.any())
.build();
}
// 构建 api文档的详细信息函数
private ApiInfo apiInfo() {
return new ApiInfoBuilder()
// 页面标题
.title("Spring Boot 测试使用 Swagger2 构建RESTful API")
// 创建人
.contact(new Contact("lichch", "https://github.com/lichch/stringboot-mybatis/tree/master",
"liCC_liCC@163.com@163.com"))
// 版本号
.version("1.0")
// 描述
.description("API 描述").build();
}
}
通过@Configuration注解,让Spring来加载该类配置,@EnableSwagger2注解来启用Swagger2。
再通过createRestApi函数创建Docket的Bean之后,apiInfo()用来创建该Api的基本信息(这些基本信息会展现在文档页面中)。select()函数返回一个ApiSelectorBuilder实例用来控制哪些接口暴露给Swagger来展现,本例采用指定扫描的包路径来定义,Swagger会扫描该包下所有Controller定义的API,并产生文档内容(除了被@ApiIgnore注解的API)。
3、编写Controller
这里开始编写自己的RESTful Controller,跟正常开发没什么区别。主要是接口方法上面新增了几个注解:
通过@ApiOperation注解来给API增加说明
通过@ApiImplicitParams、@ApiImplicitParam注解来给参数增加说明
通过@ApiIgnore来忽略那些不想让生成RESTful API文档的接口
编写SwaggerController
package cn.no7player.controller;
import java.util.ArrayList;
import java.util.List;
import org.springframework.web.bind.annotation.PathVariable;
import org.springframework.web.bind.annotation.RequestMapping;
import org.springframework.web.bind.annotation.RequestMethod;
import org.springframework.web.bind.annotation.RestController;
import com.wordnik.swagger.annotations.ApiOperation;
import cn.no7player.model.User;
/**
*
* ClassName: SwaggerController <br/>
* Function: TODO ADD FUNCTION. <br/>
* Reason: TODO ADD REASON(可选). <br/>
* date: 2017年4月13日 下午2:21:00 <br/>
*
* @author lichch
* @version
* @since JDK 1.7
*/
@RestController
@RequestMapping(value = "/users")
public class SwaggerController {
/*
* http://localhost:8080/swagger-ui.html#/
*/
/**
*
* @return
*/
@ApiOperation(value = "查询所有用户", notes = "查询得到所有用户")
@RequestMapping(method = RequestMethod.GET)
public List<User> getUsers() {
List<User> list = new ArrayList<User>();
User user = new User();
user.setName("hello");
list.add(user);
User user2 = new User();
user.setName("world");
list.add(user2);
return list;
}
@ApiOperation(value = "通过id查询用户", notes = "通过id查询用户")
@RequestMapping(value = "/{name}", method = RequestMethod.GET)
public User getUserById(@PathVariable String name) {
User user = new User();
user.setName("hello world");
return user;
}
}
完成上述代码后,打包Spring Boot程序并启动,打开浏览器访问:http://localhost:8080/swagger-ui.html,就能看到前文所展示的RESTful API的页面。
4,调试
然后我们可以对请求进行调试,是否符合RESTful请求规范,结果如图
按照如图操作,点击对应的controller 可以查看所有的请求方法和默认结果,并可以找到对应的方法进行测试 如下图