使⽤Swagger2构建强⼤的RESTful API⽂档

导语：

由于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。具体效果如下图所示：

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 。

package com.kingram.springboot.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.spi.DocumentationType;
import springfox.documentation.spring.web.plugins.Docket;
import pringfox.documentation.swagger2.annotations.EnableSwagger2;

@Configuration
@EnableSwagger2
public class Swagger2 {    
    
    @Bean    
    public Docket createRestApi() {        
    return new Docket(DocumentationType.SWAGGER_2)                
        .apiInfo(apiInfo()) .select()                
        .apis(RequestHandlerSelectors                   
        .basePackage("com.kingram.springboot"))                
        .paths(PathSelectors.any()) .build();    
    }    
    
    private ApiInfo apiInfo() {        
        return new ApiInfoBuilder()                
            .title("Spring Boot中使⽤Swagger2构建RESTful APIs")                
            .description("swagger2使用范例")                
            .termsOfServiceUrl("https://www.cnblogs.com/Kingram/")             
            .contact("Kingram")                
            .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")
public class UserController {    
    // 创建线程安全的Map    
    private static Map<Long, User> users = Collections.synchronizedMap(new HashMap<>());    
    
    @ApiOperation(value="获取⽤户列表", notes="")
    @RequestMapping(value = "/", method = RequestMethod.GET)    
    public List<User> getUserList() {           
        List<User> r = new ArrayList<>(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(@ModelAttribute 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, @ModelAttribute 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的描述信息，如下图所示。

⽂档访问与调试

在上图请求的⻚⾯中，我们看到user的Value是个输⼊框？是的，Swagger除了查看接⼝功能外，还提供了调试测试功能，我们可以点击上图中右侧的Model Schema（⻩⾊区域：它指明了User的数据结构），此时Value中就有了user对象的模板，我们只需要稍适修改，点击下⽅ “Try it out！” 按钮，即可完成了⼀次请求调⽤！

此时，你也可以通过⼏个GET请求来验证之前的POST请求是否正确。

相⽐为这些接⼝编写⽂档的⼯作，我们增加的配置内容是⾮常少⽽且精简的，对于原有代码的侵⼊也在忍受范围之内。因此，在构建RESTful API的同时，加⼊swagger来对API⽂档进⾏管理，是个不错的选择。

本文转自

程序猿DD / SpringBoot-Learning