Spring Boot中使用Swagger2构建API文档

由于Spring Boot能够快速开发、便捷部署等特性，相信有很大一部分Spring Boot的用户会用来构建RESTful API。而我们构建RESTful API的目的通常都是由于多终端的原因，这些终端会共用很多底层业务逻辑，因此我们会抽象出这样一层来同时服务于多个移动端或者Web前端。

这样一来，我们的RESTful API就有可能要面对多个开发人员或多个开发团队：IOS开发、Android开发或是Web开发等。为了减少与其他团队平时开发期间的频繁沟通成本，传统做法我们会创建一份RESTful API文档来记录所有接口细节，然而这样的做法有以下几个问题：

1）由于接口众多，并且细节复杂（需要考虑不同的HTTP请求类型、HTTP头部信息、HTTP请求内容等），高质量地创建这份文档本身就是件非常吃力的事，下游的抱怨声不绝于耳。

2）随着时间推移，不断修改接口实现的时候都必须同步修改接口文档，而文档与代码又处于两个不同的媒介，除非有严格的管理机制，不然很容易导致不一致现象。

为了解决上面这样的问题，本文将介绍RESTful API的重磅好伙伴Swagger2，它可以轻松的整合到Spring Boot中，并与Spring MVC程序配合组织出强大RESTful API文档。它既可以减少我们创建文档的工作量，同时说明内容又整合入实现代码中，让维护文档和修改代码整合为一体，可以让我们在修改代码逻辑的同时方便的修改文档说明。另外Swagger2也提供了强大的页面测试功能来调试每个RESTful API。具体效果如下图所示：

       Swagger 是一个规范和完整的框架，用于生成、描述、调用和可视化 RESTful 风格的 Web 服务。总体目标是使客户端和文件系统作为服务器以同样的速度来更新。文件的方法，参数和模型紧密集成到服务器端的代码，允许API来始终保持同步。Swagger 让部署管理和使用功能强大的API从未如此简单。以下是在Springboot中使用方式。

1、Springboot集成swagger

新建Maven工程SpringbootSwagger，在pom.xml添加依赖：

<?xml version="1.0" encoding="UTF-8"?><project xmlns="http://maven.apache.org/POM/4.0.0"         xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"         xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/xsd/maven-4.0.0.xsd">    <modelVersion>4.0.0</modelVersion>    <groupId>swagger</groupId>    <artifactId>jsx.swagger</artifactId>    <version>1.0-SNAPSHOT</version>    <packaging>jar</packaging>    <name>SpringbootSwagger</name>    <url>http://maven.apache.org</url>    <properties>        <project.build.sourceEncoding>UTF-8</project.build.sourceEncoding>        <!-- jdk版本号，angel在这里使用1.8，大家修改为大家本地配置的jdk版本号即可 -->        <java.version>1.8</java.version>    </properties>        <!--               spring boot 父节点依赖,               引入这个之后相关的引入就不需要添加version配置，               spring boot会自动选择最合适的版本进行添加。             -->    <parent>    <groupId>org.springframework.boot</groupId>    <artifactId>spring-boot-starter-parent</artifactId>    <version>1.5.3.RELEASE</version>    </parent>    <dependencies>        <!-- spring boot web支持：mvc,aop... -->        <dependency>            <groupId>org.springframework.boot</groupId>            <artifactId>spring-boot-starter-web</artifactId>        </dependency>        <!-- Swagger -->        <dependency>            <groupId>io.springfox</groupId>            <artifactId>springfox-swagger-ui</artifactId>            <version>2.7.0</version>        </dependency>        <dependency>            <groupId>io.springfox</groupId>            <artifactId>springfox-swagger2</artifactId>            <version>2.7.0</version>        </dependency>    </dependencies></project>

这里Swagger版本选择的是2.7.0，解决了前面版本参数结构的写问题。

2、创建Swagger2配置类

package com.springboot.swagger;import com.google.common.base.Predicates;import io.swagger.annotations.Api;import org.springframework.context.annotation.Bean;import org.springframework.context.annotation.Configuration;import org.springframework.http.ResponseEntity;import org.springframework.web.context.request.async.DeferredResult;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;import java.util.ArrayList;/** * Swagger配置类: * * @author jiasx * @create 2017/9/11 15:08 **/@Configuration@EnableSwagger2public class SwaggerConfig {    /**     * SpringBoot默认已经将classpath:/META-INF/resources/和classpath:/META-INF/resources/webjars/映射     * 所以该方法不需要重写，如果在SpringMVC中，需要在xml中定义     * 重写该方法需要 extends WebMvcConfigurerAdapter     *     *///    @Override//    public void addResourceHandlers(ResourceHandlerRegistry registry) {//        registry.addResourceHandler("swagger-ui.html")//                .addResourceLocations("classpath:/META-INF/resources/");////        registry.addResourceHandler("/webjars/**")//                .addResourceLocations("classpath:/META-INF/resources/webjars/");//    }    /**     * 可以定义多个组，比如本类中定义把test和demo区分开了     * （访问页面就可以看到效果了）     */    @SuppressWarnings("unchecked")    @Bean    public Docket testApi() {        Docket docket = new Docket(DocumentationType.SWAGGER_2)                .groupName("Api")                .genericModelSubstitutes(DeferredResult.class)                .useDefaultResponseMessages(false)                .forCodeGeneration(true)                .pathMapping("/")// base，最终调用接口后会和paths拼接在一起                .select()                //                .apis(RequestHandlerSelectors.basePackage("com.swagger.test"))//根据包名去过滤接口                .apis(RequestHandlerSelectors.withClassAnnotation(Api.class))//根据注解去过滤接口                .paths(Predicates.or(PathSelectors.regex("/api/.*")))//通过路径的方式过滤的接口                .build()                .apiInfo(testApiInfo());        ;        return docket;    }    @SuppressWarnings("unchecked")    @Bean    public Docket demoApi() {        return new Docket(DocumentationType.SWAGGER_2)                .groupName("Demo")//                .genericModelSubstitutes(DeferredResult.class)                .genericModelSubstitutes(ResponseEntity.class)                .useDefaultResponseMessages(false)                .forCodeGeneration(false)                .pathMapping("/")                .select()//                .apis(RequestHandlerSelectors.basePackage("com.swagger.test"))//根据包名去过滤接口                .apis(RequestHandlerSelectors.withClassAnnotation(Api.class))//根据注解去过滤接口                .paths(Predicates.or(PathSelectors.regex("/demo/.*")))//过滤的接口                .build()                .apiInfo(demoApiInfo());    }    private ApiInfo testApiInfo() {        ApiInfo apiInfo = new ApiInfo("Test相关接口",//大标题                "Test相关接口，主要用于测试.",//小标题                "1.0",//版本                "http://baidu.com",                new Contact("测试人", "", ""),//作者                "一只小蚂蚁",//链接显示文字                "http://baidu.com",//网站链接                new ArrayList<>()        );        return apiInfo;    }    private ApiInfo demoApiInfo() {        ApiInfo apiInfo = new ApiInfo("Demo相关接口",//大标题                "Demo相关接口，主要用于demo演示.",//小标题                "1.0",//版本                "http://baidu.com",                new Contact("演示人", "", ""),//作者                "一只小蚂蚁",//链接显示文字                "http://baidu.com",//网站链接                new ArrayList<>()        );        return apiInfo;    }}

上面代码通过@Configuration注解，让Spring来加载该类配置。再通过@EnableSwagger2注解来启用Swagger2。再通过createRestApi函数创建Docket的Bean之后，apiInfo()用来创建该Api的基本信息（这些基本信息会展现在文档页面中）。select()函数返回一个ApiSelectorBuilder实例用来控制哪些接口暴露给Swagger来展现

       经过这2步配置后，我们启动服务后，访问：http://localhost:8080/swagger-ui.html 就完成了集成。

3、编写Controller测试类

路径为/api/*的controller，可以匹配在SwaggerConfig中配置的api组，代码如下：

package com.swagger.test;/** * Swagger2默认将所有的Controller中的RequestMapping方法都会暴露，然而在实际开发中，我们并不一定需要把所有API都提现在文档中查看，这种情况下，使用注解@ApiIgnore来解决，如果应用在Controller范围上，则当前Controller中的所有方法都会被忽略，如果应用在方法上，则对应用的方法忽略暴露API。 注解@ApiOperation和@ApiParam可以理解为API说明，如果我们不使用这样注解进行说明，Swagger2也是有默认值的。 */import io.swagger.annotations.*;import org.springframework.web.bind.annotation.*;import javax.validation.Valid;import java.util.List;/** * 增加api注解的控制类 * * @author jiasx * @create 2017-09-09 14:57 **/@RequestMapping("/api")@RestController@Api(tags = {"Api接口"},description="api接口服务")public class ApiCityController {    @PostMapping(value = "/show")// 这里指定RequestMethod，如果不指定Swagger会把所有RequestMethod都输出，在实际应用中，具体指定请求类型也使接口更为严谨。    @ApiOperation(value="测试接口", notes="根据名称查询城市测试接口")    public String testStr(            @ApiParam(name="name", value="城市姓名",required=true)            @RequestParam(name = "name") String cityName){        return "根据名称查询城市成功";    }    /**     * 查询城市     * @param city     * @return     */    @PostMapping("get")    @ApiOperation(value="查询城市", notes="根据条件查询单个城市",httpMethod = "POST", response = City.class)    public City getCity(@RequestBody City city) {        city.setProvience("中国分省");        return city;    }    /**     * 查询城市     * @param id     * @param name     * @param province     * @return     */    @PostMapping("insert")    @ApiOperation(value="新增城市", notes="新增城市",httpMethod = "POST", response = City.class)    @ApiImplicitParams({            @ApiImplicitParam(name = "id", value = "ID", required = true, dataType = "String"),            @ApiImplicitParam(name = "name", value = "城市名称", required = true, dataType = "String"),            @ApiImplicitParam(name = "province", value = "所属省份", required = true, dataType = "String")    })    public City insert(String id,String name,String province) {        return new City(id,name,province);    }}

路径为/demo/*的controller，可以匹配在SwaggerConfig中配置的demo组，代码如下：

package com.swagger.test;/** * Swagger2默认将所有的Controller中的RequestMapping方法都会暴露，然而在实际开发中，我们并不一定需要把所有API都提现在文档中查看，这种情况下，使用注解@ApiIgnore来解决，如果应用在Controller范围上，则当前Controller中的所有方法都会被忽略，如果应用在方法上，则对应用的方法忽略暴露API。 注解@ApiOperation和@ApiParam可以理解为API说明，多动手尝试就很容易理解了。 如果我们不使用这样注解进行说明，Swagger2也是有默认值的，没什么可说的试试就知道了。 * */import io.swagger.annotations.*;import org.springframework.web.bind.annotation.*;/** * 增加api注解的控制类 * * @author jiasx * @create 2017-09-09 14:57 **/@RequestMapping("/demo")@RestController@Api(tags = {"Demo接口"},description="Demo接口服务")public class DemoController {    @PostMapping(value = "/show")// 这里指定RequestMethod，如果不指定Swagger会把所有RequestMethod都输出，在实际应用中，具体指定请求类型也使接口更为严谨。    @ApiOperation(value="测试接口", notes="根据名称查询城市测试接口")    public String testStr(            @ApiParam(name="name", value="城市姓名",required=true)            @RequestParam(name = "name") String cityName){        return "根据名称查询城市成功";    }    /**     * 查询城市     * @param city     * @return     */    @PostMapping("get")    @ApiOperation(value="查询城市", notes="根据条件查询单个城市",httpMethod = "POST", response = City.class)    public City getCity(@RequestBody City city) {        city.setProvience("中国分省");        return city;    }    /**     * 查询城市     * @param id     * @param name     * @param province     * @return     */    @PostMapping("insert")    @ApiOperation(value="新增城市", notes="新增城市",httpMethod = "POST", response = City.class)    @ApiImplicitParams({            @ApiImplicitParam(name = "id", value = "ID", required = true, dataType = "String"),            @ApiImplicitParam(name = "name", value = "城市名称", required = true, dataType = "String"),            @ApiImplicitParam(name = "province", value = "所属省份", required = true, dataType = "String")    })    public City insert(String id,String name,String province) {        return new City(id,name,province);    }}

代码中都加了注释，相信有java基础的很容易就看懂，我就不一一解释了。

4、测试集成效果

再次访问：http://127.0.0.1:8080/swagger-ui.html，即可看到效果。

选择默认的api分组：

选择demo分组