Spring Boot进阶1 - 整合Swagger2自动生成RESTful API文档

本文将介绍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 可以查看所有的请求方法和默认结果，并可以找到对应的方法进行测试 如下图

源码下载

https://github.com/lichch/stringboot-mybatis.git