【SpringBoot探索四】SpringBoot项目集成Swagger2管理接口文档

1.使用swagger2的好处

在日常开发中，避免不了的就是为接口编写文档。这需要占用我们一定的开发时间。同时还需要维护接口文档，当接口字段有变化，我们需要立即更新文档，而且还需要告知前端。进行修改。现在我们可以使用swagger2来帮助我们在线生成接口文档，接口文档自动更新等等，接口测试等等。swagger2使用很简单，其只会对现在的代码结构有微小的变化。这也是合理的！

2.继承swagger2

1.在pom文件中添加上依赖

<!--swagger依赖-->
        <dependency>
            <groupId>io.springfox</groupId>
            <artifactId>springfox-swagger2</artifactId>
            <version>2.7.0</version>
        </dependency>
        <dependency>
            <groupId>io.springfox</groupId>
            <artifactId>springfox-swagger-ui</artifactId>
            <version>2.7.0</version>
        </dependency>

2.添加Swagger2 config

package com.my.webapp.app;

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;

/**
 */
@Configuration
@EnableSwagger2
public class Swagger2 {
    @Bean
    public Docket createRestApi() {
        return new Docket(DocumentationType.SWAGGER_2)
                .apiInfo(apiInfo())
                .select()
                .apis(RequestHandlerSelectors.basePackage("com.my.webapp.app.controller"))//暴露指定包下的接口说明，可以指定多个包
                .paths(PathSelectors.any())
                .build();
    }

    private ApiInfo apiInfo() {
        return new ApiInfoBuilder()
                .title("webapp接口文档")
                .description("webapp开放接口相关文档，仅供学习，研究使用！")
                .termsOfServiceUrl("http://blog.csdn.net/struggling_rong")
                .contact(new Contact("struggling_rong", "http://blog.csdn.net/struggling_rong", "[email protected]"))
                .version("1.0.0")
                .build();
    }
}

注意需要该Config类所处的包要被springboot启动时扫描到swagger2才能生效。

否则会出现如下提示

3.为接口编写说明

接口类，方法，参数，返回值的说明都是通过swagger2提供的注解来完成

package com.my.webapp.app.controller;

import com.my.webapp.app.controller.param.EncryptParam;
import com.my.webapp.app.controller.response.Response;
import io.swagger.annotations.*;
import org.jasypt.encryption.StringEncryptor;
import org.slf4j.Logger;
import org.slf4j.LoggerFactory;
import org.springframework.beans.factory.annotation.Autowired;
import org.springframework.beans.factory.annotation.Value;
import org.springframework.http.MediaType;
import org.springframework.web.bind.annotation.*;

import javax.validation.Valid;

/**
 */
@Api(tags = "测试", produces = MediaType.APPLICATION_JSON_VALUE)//整个类的说明
@RestController
@RequestMapping("/test")
public class TestController extends BaseController {
    private final Logger logger = LoggerFactory.getLogger(this.getClass());

    @Value("${spring.profiles.active}")
    private String profileActive;

    @Autowired
    private StringEncryptor jasyptStringEncryptor;

    @ApiOperation(value = "加密", produces = MediaType.APPLICATION_JSON_VALUE)//方法说明
    @ApiResponses(value = {@ApiResponse(code = 200, message = "成功", response = Response.class)})//响应数据说明，可以有多个
    @RequestMapping(value = "/encrypt", method = RequestMethod.POST)
    public Response encrypt(@RequestBody @Valid EncryptParam param) {
        return Response.success(jasyptStringEncryptor.encrypt(param.getText()));
    }

    @RequestMapping(value = "/decrypt/{cipherText}", method = RequestMethod.POST)
    public Response decrypt(@PathVariable @ApiParam(value = "密文", required = true) String cipherText) {
        return Response.success(jasyptStringEncryptor.decrypt(cipherText));
    }

}

@Api(tags=”测试”, produces = MediaType.APPLICATION_JSON_VALUE)
作用于类，表示该类为swagger2的一个资源，我们还可以使用@ApiIgnore让swagger2忽略该类

tags: 说明

produces: 数据格式

@ApiOperation(value = “加密”, produces = MediaType.APPLICATION_JSON_VALUE)

作用于方法，用于说明方法

value: 说明

produces: 数据格式

@ApiResponses(value = {@ApiResponse(code = 200, message = “成功”, response = Response.class)})
作用于方法，说明方法的返回数据，

value: 多个@ApiResponse集合

@ApiResponse：某种情况的回复数据，可以有多个

code：响应code 如200, 404, 201等

message: 响应数据说明

response: 响应数据类型

@ApiParam(value=”密文”, required = true)

作用于方法，说明参数

value: 说明

required: 是否必填

当参数是个复杂的类，我们还可以使用@ApiModule和@ApiModelProperty两个注解来搭配使用

package com.my.webapp.app.controller.param;

import io.swagger.annotations.ApiModel;
import io.swagger.annotations.ApiModelProperty;
import org.hibernate.validator.constraints.NotBlank;

/**
 */
@ApiModel("加密参数")
public class EncryptParam {

    @ApiModelProperty(value = "明文", required = true)//参数说明
    @NotBlank
    private String text;

    public String getText() {
        return text;
    }

    public void setText(String text) {
        this.text = text;
    }
}

@ApiModule(“加密参数”)

用于整个类的说明

@ApiModelProperty(value = “明文”, required = true)

用于某个字段的说明

value：说明

required: 是否必填

4.使用swagger2生成的在线文档

启动项目后
通过浏览器打开
http://localhost:8080/swagger-ui.html

则效果如下：

如果我们需要测试该接口，可以点击try it out 按钮进行测试。

参考链接：

Spring Boot中使用Swagger2构建强大的RESTful API文档

 swagger2常用注解说明