SpringBoot集成Swagger2

一、前言

      现在测试都提倡自动化测试，那我们作为后台的开发人员，也得进步下啊，以前用postman来测试后台接口，那个麻烦啊，一个字母输错就导致测试失败，现在swagger的出现可谓是拯救了这些开发人员，便捷之处真的不是一点两点。如果不知道什么是swagger？那说明你还是个手写接口文档的小程序员^_^，下面就稍微解释下，什么是swagger，个人理解哈，如果不对的地方，请各位大佬指正

      编写和维护接口文档是每个程序员的职责，根据 Swagger2 可以快速帮助我们编写最新的API接口文档，再也不用担心开会前仍忙于整理各种资料了，间接提升了团队开发的沟通效率。常用注解swagger通过注解表明该接口会生成文档，包括接口名、请求方法、参数、返回信息的等等。

二、开始引入

      1、maven引入相关的依赖

<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、新建swagger配置类

package com.zywork.configuration;

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;

/**
 * Swagger2配置<br/>
 *
 * 创建于2019-01-16<br/>
 *
 * @author 危锦辉
 * @version 1.0
 */
@Configuration
@EnableSwagger2
public class Swagger2Config {

    @Bean
    public Docket createRestApi() {
        return new Docket(DocumentationType.SWAGGER_2)
                .apiInfo(apiInfo())
                .select()
                .apis(RequestHandlerSelectors.basePackage("com.zywork.controller"))
                .paths(PathSelectors.any())
                .build();
    }

    private ApiInfo apiInfo() {
        return new ApiInfoBuilder()
                .title("RedisManager接口文档")
                .contact(new Contact("危锦辉", "http://wjhsmart.vip", "wjhsmarter@126.com"))
                .version("1.0")
                .description("RedisManager接口文档")
                .build();
    }



}

      其实这个配置类，只要了解具体能配置哪些东西就好了，毕竟这个东西配置一次之后就不用再动了。 特别要注意的是里面配置了api文件也就是controller包的路径，不然生成的文档扫描不到接口。

      3、在HelloController.java中增加注解

package com.zywork.controller;

import com.zywork.vo.ResponseStatusVO;
import io.swagger.annotations.Api;
import io.swagger.annotations.ApiOperation;
import org.springframework.web.bind.annotation.GetMapping;
import org.springframework.web.bind.annotation.RequestMapping;
import org.springframework.web.bind.annotation.RestController;

@Api("用来测试的Hello API")
@RestController
@RequestMapping("/hello")
public class HelloController {


    @ApiOperation(value="输出Hello World", notes="返回json文本信息")
    @GetMapping("/hello")
    public ResponseStatusVO hello() {
        return ResponseStatusVO.ok("Hello World!", null);
    }
}

      这里顺便附上自己封装的响应类

ResponseStatusEnum.java

package com.zywork.enums;

/**
 * 响应状态枚举<br/>
 * 创建于2019-01-16<br/>
 *
 * @author 危锦辉
 * @version 1.0
 */
public enum ResponseStatusEnum {

    OK(1001, "成功"),
    ERROR(1002, "系统错误"),
    DATA_ERROR(1003, "参数错误"),
    AUTHENTICATION_FAILURE(1004, "用户认证失败"),
    AUTHENTICATION_ERROR(1005, "未认证的用户"),
    AUTHENTICATION_TOKEN_ERROR(1006, "用户Token错误"),
    AUTHORIZATION_ERROR(1007, "未授权的用户");

    private Integer code;
    private String message;

    ResponseStatusEnum(Integer code, String message) {
        this.code = code;
        this.message = message;
    }

    public Integer getCode() {
        return code;
    }

    public void setCode(Integer code) {
        this.code = code;
    }

    public String getMessage() {
        return message;
    }

    public void setMessage(String message) {
        this.message = message;
    }
}

BaseVO.java

package com.zywork.vo;

import java.io.Serializable;

/**
 * 所有VO类的父类<br/>
 * 创建于2018-01-16<br/>
 *
 * @author 危锦辉
 * @version 1.0
 */
public class BaseVO implements Serializable {
    private static final long serialVersionUID = -3018149472984622809L;
}

ResponseStatusVO.java

package com.zywork.vo;

import com.zywork.enums.ResponseStatusEnum;

/**
 * 控制器结果，通常都是在页面上执行添加，删除，状态改变等操作时，由控制器返回执行结果的JSON格式数据到前端页面<br/>
 * 创建于2019-01-16<br/>
 *
 * @author 危锦辉
 * @version 1.0
 * @see ResponseStatusEnum
 */
public class ResponseStatusVO extends BaseVO {

    private static final long serialVersionUID = 4997020566681368159L;

    // 状态码
    private Integer code;
    // 返回消息
    private String message;
    // 返回数据
    private Object data;

    public ResponseStatusVO() {}

    public ResponseStatusVO(Integer code, String message, Object data) {
        this.code = code;
        this.message = message;
        this.data = data;
    }

    public Integer getCode() {
        return code;
    }

    public void setCode(Integer code) {
        this.code = code;
    }

    public String getMessage() {
        return message;
    }

    public void setMessage(String message) {
        this.message = message;
    }

    public Object getData() {
        return data;
    }

    public void setData(Object data) {
        this.data = data;
    }

    /**
     * 获取表示执行成功的结果
     *
     * @param code 状态码
     * @param message 需要返回到前端页面的提示信息
     * @param data 返回数据
     */
    @Deprecated
    public void okStatus(Integer code, String message, Object data) {
        setCode(code);
        setMessage(message);
        setData(data);
    }

    /**
     * 获取表示执行成功的结果
     *
     * @param code 状态码
     * @param message 需要返回到前端页面的提示信息
     * @param data 返回数据
     * @return
     */
    public static ResponseStatusVO ok(Integer code, String message, Object data) {
        return new ResponseStatusVO(code, message, data);
    }

    /**
     * 获取表示执行成功的结果
     *
     * @param message 需要返回到前端页面的提示信息
     * @param data 返回数据
     * @return
     */
    public static ResponseStatusVO ok(String message, Object data) {
        return new ResponseStatusVO(ResponseStatusEnum.OK.getCode(), message, data);
    }

    /**
     * 获取表示执行失败的结果
     *
     * @param code 状态码
     * @param message 需要返回到前端页面的提示信息
     * @param data 返回数据
     */
    @Deprecated
    public void errorStatus(Integer code, String message, Object data) {
        setCode(code);
        setMessage(message);
        setData(data);
    }

    /**
     * 获取表示执行失败的结果
     *
     * @param code 状态码
     * @param message 需要返回到前端页面的提示信息
     * @param data 返回数据
     * @return
     */
    public static ResponseStatusVO error(Integer code, String message, Object data) {
        return new ResponseStatusVO(code, message, data);
    }

    /**
     * 获取表示执行失败的结果
     *
     * @param message 需要返回到前端页面的提示信息
     * @param data 返回数据
     * @return
     */
    public static ResponseStatusVO error(String message, Object data) {
        return new ResponseStatusVO(ResponseStatusEnum.ERROR.getCode(), message, data);
    }

    /**
     * 获取表示数据错误的结果
     *
     * @param code 状态码
     * @param message 需要返回到前端页面的提示信息
     * @param data 返回数据
     */
    @Deprecated
    public void dataErrorStatus(Integer code, String message, Object data) {
        setCode(code);
        setMessage(message);
        setData(data);
    }

    /**
     * 获取表示数据错误的结果
     *
     * @param code 状态码
     * @param message 需要返回到前端页面的提示信息
     * @param data 返回数据
     * @return
     */
    public static ResponseStatusVO dataError(Integer code, String message, Object data) {
        return new ResponseStatusVO(code, message, data);
    }

    /**
     * 获取表示数据错误的结果
     *
     * @param message 需要返回到前端页面的提示信息
     * @param data 返回数据
     * @return
     */
    public static ResponseStatusVO dataError(String message, Object data) {
        return new ResponseStatusVO(ResponseStatusEnum.DATA_ERROR.getCode(), message, data);
    }

    /**
     * 获取未认证的用户结果
     * @return
     */
    public static ResponseStatusVO authenticationError() {
        return new ResponseStatusVO(ResponseStatusEnum.AUTHENTICATION_ERROR.getCode(), ResponseStatusEnum.AUTHENTICATION_ERROR.getMessage(), null);
    }

    /**
     * 获取未授权的用户结果
     * @return
     */
    public static ResponseStatusVO authorizationError() {
        return new ResponseStatusVO(ResponseStatusEnum.AUTHORIZATION_ERROR.getCode(), ResponseStatusEnum.AUTHORIZATION_ERROR.getMessage(), null);
    }

    @Override
    public String toString() {
        return "ResponseStatusVO{" +
                "code=" + code +
                ", message='" + message + '\'' +
                ", data=" + data +
                '}';
    }
}

      4、访问：http://localhost:8080/swagger-ui.html，如果出现和下图一样的，说明配置成功

直接浏览器访问接口路径是：http://localhost:8080/hello/hello

      5、swagger注解

• @Api：修饰整个类，描述Controller的作用
• @ApiOperation：描述一个类的一个方法，或者说一个接口
• @ApiParam：单个参数描述
• @ApiModel：用对象来接收参数
• @ApiProperty：用对象接收参数时，描述对象的一个字段
• @ApiResponse：HTTP响应其中1个描述
• @ApiResponses：HTTP响应整体描述
• @ApiIgnore：使用该注解忽略这个API
• @ApiError ：发生错误返回的信息
• @ApiImplicitParam：一个请求参数
• @ApiImplicitParams：多个请求参数