SpringBoot整合Swagger2

Swagger2简介

在前后端分离开发中，为了减少与其他团队的沟通成本，一般构建一份RESTFUL API文档来描述所有的接口信息，但是这种做法有很大的弊端，分别说明如下：

• 接口众多，编写RESTful API文档工作量巨大，因为RESTful API文档不仅要包含接口的基本信息，如接口地址，接口请求参数以及接口返回值等，还要包含HTTP请求类型，HTTP请求头、请求参数类型、返回值类型、所需权限等。
• 维护不方便，一旦接口发生变化，就要修改文档。
• 接口测试不方便，一般只能借助第三方工具（如postman）来测试。

Swagger2是一个开源软件框架，可以帮助开发人员设计、构建、记录和使用RESTful Web服务，它将代码和文档融为一体，可以完美解决上面描述的问题，是开放人员将大部分精力集中到业务中，而不是繁杂琐碎的文档中。

整合SpringBoot

首先创建SpringBoot Web项目，添加Swagger2相关依赖，代码如下：

		<!-- Swagger2相关依赖-->
        <dependency>
            <groupId>io.springfox</groupId>
            <artifactId>springfox-swagger2</artifactId>
            <version>2.9.2</version>
        </dependency>
        <dependency>
            <groupId>io.springfox</groupId>
            <artifactId>springfox-swagger-ui</artifactId>
            <version>2.9.2</version>
        </dependency>

接下来创建Swagger2得配置类，代码如下：

/**
 * Swagger2配置类
 */
@Configuration
@EnableSwagger2
public class SwaggerConfig {

    @Bean
    Docket docket(){
        return new Docket(DocumentationType.SWAGGER_2)
                .select()
                .apis(RequestHandlerSelectors.basePackage("com.learn.qqemail.controller"))
                .paths(PathSelectors.any())
                .build().apiInfo(new ApiInfoBuilder()
                .description("微人事接口测试文档")
                .contact(new Contact("hjw","https://github.com/woxiangwoshi/monkey","17376551958@163.com"))
                .version("v1.0")
                .title("API测试文档")
                .license("Apache2.0")
                .licenseUrl("http://www.apache.org/licenses/LICENSE-2.0")
                .build());
    }
}

代码解释：

• 首先通过@EnableSwagger注解开启Swagger2，然后最主要的是配置一个Docket。
• 通过apis方法配置要扫描的controller位置，通过paths方法配置路径。
• 在apiInfo中构建文档的基本信息，例如描述、联系人信息、版本、标题等。

Swagger2配置成功后，接下来就可以开发接口了，代码如下：

@RestController
@Api(tags = "用户数据接口")
public class UserController {

    @ApiOperation(value = "查询用户",notes = "根据id查询用户")
    @ApiImplicitParam(paramType = "path",name = "id",value = "用户id",required = true)
    @GetMapping("/user/{id}")
    public String getUserById(@PathVariable Integer id){
        return "/user/"+id;
    }

    @ApiResponses({
            @ApiResponse(code = 200,message = "删除成功！"),
            @ApiResponse(code = 500,message = "删除失败！")
    })
    @ApiOperation(value = "删除用户",notes = "通过id删除用户")
    @DeleteMapping("/user/{id}")
    public Integer deleteUserById(@PathVariable Integer id){
        return id;
    }

    @ApiOperation(value = "添加用户",notes = "添加一个用户，传入用户名和地址")
    @ApiImplicitParams({
            @ApiImplicitParam(paramType = "query",name = "username",value = "用户名",required = true,defaultValue = "hjw"),
            @ApiImplicitParam(paramType = "query", name = "address",value = "用户地址",required = true,defaultValue = "hangzhou")
    })
    @PostMapping("/user")
    public String addUser(@RequestParam String username,@RequestParam String address){
        return username+":"+address;
    }


    @ApiOperation(value = "修改用户",notes = "修改用户，传入用户信息")
    @PutMapping("/user")
    public String updateUser(@RequestBody User user){
        return user.toString();
    }

    @GetMapping("/ignore")
    @ApiIgnore
    public void ingoreMethod(){

    }

}

Uesr实体类

@ApiModel(value = "用户实体类",description = "用户信息描述类")
public class User {
    @ApiModelProperty(value = "用户名")
    private String username;
    @ApiModelProperty(value = "用户地址")
    private String address;

    public String getUsername() {
        return username;
    }

    public void setUsername(String username) {
        this.username = username;
    }

    public String getAddress() {
        return address;
    }

    public void setAddress(String address) {
        this.address = address;
    }

    @Override
    public String toString() {
        return "User{" +
                "username='" + username + '\'' +
                ", address='" + address + '\'' +
                '}';
    }
}

代码解释：

• @Api注解用在类上，用来扫描整个Controller信息。
• @ApiOperation注解用在开发方法上，用来描述一个方法的基本信息，value是对方法作用的一个简短描述，notes则用来备注该方法的详细作用。
• @ApiImplicitParam注解用在方法上，用来描述方法的参数，paramType是指方法参数的类型，可选值有path（参数获取方式@PathVariable）、query（参数获取方式@RequestParam）、header（参数获取方式@RequestHeader）、body以及form；name表示参数名称，和参数变量对应；value是参数的描述信息；required表示该字段是否必填；defaultValue表示该字段的默认值。注意，这里的required和defaultValue等字段只是文档上的约束描述，并不能真正的约束接口，约束接口还需要再@RequestParam中添加相关属性。
• @ApiReponse注解是对响应结果的描述，code表示响应码，message表示相应的描述信息，若有多个@ApiReponse，则放在一个@ApiReponses中。
• 在updateUser方法中，使用@RequestBody注解来接受数据，此时可以通过@ApiModel注解和@ApiModelProperty注解配置User对象的描述信息。
• @ApiIgnore注解表示不对某个接口生成文档。

接下来启动项目，在浏览器输入http://localhost:8080/swagger-ui.html即可看到接口文档。