Java-spring boot整合swagger2

---

前言

Swagger UI2是为了解决程序员日常编写文档的烦恼,而推出的根据注解可以自动生成API文档的框架,也是当下比较好用的API框架

一、什么情况下使用？

可以在前后端分离时,接口较多的情况下使用swaggerUI2

二、使用步骤

1.Maven依赖配置

下面是使用Swagger2所用的依赖：

 <!-- swagger2 核心包-->
        <dependency>
            <groupId>io.springfox</groupId>
            <artifactId>springfox-swagger2</artifactId>
            <version>2.9.2</version>
        </dependency>
         <!-- 这个是原本swagger2UI的jar包但是使用不是特别舒服所以引用下面这个swagger-bootstrap-ui-->
        <!--        <dependency>-->
        <!--            <groupId>io.springfox</groupId>-->
        <!--            <artifactId>springfox-swagger-ui</artifactId>-->
        <!--            <version>2.9.2</version>-->
        <!--        </dependency>-->
        <!-- 使用较为好看的swagger-bootstrap-ui 替代了原有的ui-->
        <dependency>
            <groupId>com.github.xiaoymin</groupId>
            <artifactId>swagger-bootstrap-ui</artifactId>
            <version>1.9.2</version>
        </dependency>

2.使用步骤

第一步、添加项目配置

主要代码如下（示例）：

/**
 * @Author：zeng
 * @Date： created in 20:50 2021/4/10
 */
@Configuration
@EnableSwagger2
public class Swagger2Config extends WebMvcConfigurationSupport {
    // api接口包扫描路径
    @Value("${swagger.package}")
    public  String SWAGGER_SCAN_BASE_PACKAGE;
    // 接口文档版本
    @Value("${swagger.version}")
    public  String VERSION;
	//是否启动swaggerUI
    @Value("${swagger.enable}")
    public  boolean ENABLE;
    /**
     * 因为 Swagger2的资源文件都是在jar包里面，如果不在此处配置加载静态资源，
     * 可能会导致请求http://localhost:端口/doc.html失败
     *  <!--swagger资源配置-->
     *  <mvc:resources location="classpath:/META-INF/resources/" mapping="doc.html"/>
     *  <mvc:resources location="classpath:/META-INF/resources/webjars/" mapping="/webjars/**"/>
     * @param registry
     */
    @Override
    protected void addResourceHandlers(ResourceHandlerRegistry registry) {
        //新的swagger-bootstrap-ui对应的api页面
        registry.addResourceHandler("doc.html")
        //想要使用老版的则打开这个注解,并且注释上面的
        //registry.addResourceHandler("swagger-ui.html")
                .addResourceLocations("classpath:/META-INF/resources/");

        registry.addResourceHandler("/webjars/**")
                .addResourceLocations("classpath:/META-INF/resources/webjars/");
    }

    /**
     * 返回构建器
     * @return
     */
    @Bean
    public Docket createRestApi() {
        //返回响应状态信息统一返回
        List<ResponseMessage> responseMessageList = new ArrayList<>();
        responseMessageList.add(new ResponseMessageBuilder().code(404).message("未找到资源").responseModel(new ModelRef("AjaxResult")).build());
        responseMessageList.add(new ResponseMessageBuilder().code(500).message("服务器内部错误").responseModel(new ModelRef("ApiError")).build());
        responseMessageList.add(new ResponseMessageBuilder().code(503).message("服务外部异常").responseModel(new ModelRef("ApiError")).build());
        //一个构建器，目的是作为SpringFox框架的主要接口。
        return new Docket(DocumentationType.SWAGGER_2)
                //请求,对应的状态
                .globalResponseMessage(RequestMethod.GET, responseMessageList)
                .globalResponseMessage(RequestMethod.POST, responseMessageList)
                .globalResponseMessage(RequestMethod.PUT, responseMessageList)
                .globalResponseMessage(RequestMethod.DELETE, responseMessageList)
                //这里配置文档标题作者版本等信息
                .apiInfo(apiInfo())
                // base，最终调用接口后会和paths拼接在一起
                .pathMapping("/")
                // 选择那些路径和api会生成document
                .select()
                //扫描路径,一般为controller路径
                .apis(RequestHandlerSelectors.basePackage(SWAGGER_SCAN_BASE_PACKAGE))
                //(对指定路径进行监控)过滤的接口
                .paths(PathSelectors.any())
                .build()
                //关闭或启动swagger2UI true开启|false关闭
                .enable(ENABLE);

    }

    private ApiInfo apiInfo() {
        return new ApiInfoBuilder()
                //文档首页标题
                .title("接口文档")
                //文档简绍
                .description("服务端接口文档，服务于程序猿")
                //文档创作者
                .contact("zeng")
                //文档版本
                .version(VERSION)
                .build();
    }
}

@Value注解是引用yml里面的配置用于统一开发,测试,生产中是否使用swaggerUI与版本控制
配置application.yml

swagger:
  package: com.*.*.controller
  version: 1.0.0
  enable: true

com...controller属于自己项目的controller路径

效果1:
此时启动项目在浏览器上面输入http://127.0.0.1:端口/doc.html 就可以看到swagger2页面了.
如图所示:

这时说明swaggerUI文档已经加载成功

第二步、创建controller使用注解，形成接口集合以及接口页面

首先创建controller文件夹，在创建一个UserContoller类

在里面添加方法，在加上地址以及swagger对应注解

/**
 * @author Robot
 * @date 21/04/20
 */
@Controller
@RequestMapping("user")
@Api(tags = "用户接口集合",value = "用户相关接口的集合")
public class UserController {
    @GetMapping("getUser")
    @ApiOperation(value="查询用户接口", notes="查询用户信息接口",httpMethod = "GET")
    public void getUser(){
    }
}

效果图：

第三步、接口添加参数及返回值

在方法中添加username参数，修改注解Controller为RestController

@RestController
@RequestMapping("user")
@Api(tags = "用户接口集合",value = "用户相关接口的集合")
public class UserController {
    @GetMapping("getUser")
    @ApiImplicitParam(name = "username", value = "用户名", required = true, paramType="query")
    @ApiOperation(value="查询用户接口", notes="查询用户信息接口",httpMethod = "GET")
    public String getUser(@RequestParam String username){
        return username;
    }
}

添加@ApiImplicitParam对应接口就会有这个参数描述

调试时的参数

到这一步普通的请求就可以这么使用了，接下来是关于实体类的设置，正式开发的配置了

第四步、开发配置

需要创建四个类

①.返回结果封装类

/**
 * 统一API响应结果封装
 *
 * @author zeng
 */
@ApiModel("统一API响应结果封装")
public class AjaxResult<T> implements Serializable {
    /**
     * 状态码
     */
    @ApiModelProperty(value = "成功失败的标志",required = true)
    private final int code;
    /**
     * 响应信息，用来说明响应情况
     */
    @ApiModelProperty(value = "操作响应信息",required = true)
    private final String message;
    /**
     * 响应的具体数据
     */
    @ApiModelProperty(value = "响应数据",required = false)
    private T data;



    public AjaxResult(T data) {
        this(ResultCode.SUCCESS, data);
    }

    public AjaxResult(ResultCode resultCode, T data) {
        this.code = resultCode.getCode();
        this.message = resultCode.getMsg();
        this.data = data;
    }
    public AjaxResult(ResultCode resultCode) {
        this.code = resultCode.getCode();
        this.message = resultCode.getMsg();
    }


    /**
     * 返回成功消息
     *
     * @param data 数据对象
     * @return 成功消息
     */
    public static <T> AjaxResult<T>  success(T data) {
        return new AjaxResult<>(ResultCode.SUCCESS, data);
    }


    /**
     * 返回成功消息
     *
     * @return 成功消息
     */
    public static <T> AjaxResult<T>  success() {
        return new AjaxResult<>(ResultCode.SUCCESS);
    }


    /**
     * 返回失败消息
     *
     * @param resultCode 自定义对象
     * @return 自定义失败消息
     */
    public static <T> AjaxResult<T>  error(ResultCode resultCode) {
        return new AjaxResult<>(resultCode);
    }
    /**
     * 返回警告消息
     *
     * @param data 数据对象
     * @return 警告消息
     */
    public static <T> AjaxResult<T> error500(T data) {
        return new AjaxResult<>(ResultCode.SYSTEM_ERROR, data);
    }


    /**
     * 返回警告消息
     *
     * @return 警告消息
     */
    public static <T> AjaxResult<T> error500() {
        return new AjaxResult<>(ResultCode.SYSTEM_ERROR);
    }

    /**
     * 返回错误消息
     *
     * @param data 数据对象
     * @return 警告消息
     */
    public static <T> AjaxResult<T> error400(T data) {
        return new AjaxResult<>(ResultCode.ERROR, data);
    }
    /**
     * 返回错误消息
     *
     * @return 警告消息
     */
    public static <T> AjaxResult<T> error400() {
        return new AjaxResult<>(ResultCode.ERROR);
    }

    /**
     * 未经过身份认证
     * @param <T> 返回值类型
     * @return
     */
    public static <T> AjaxResult<T> authError(){
        return new AjaxResult<T>(ResultCode.AUTH_ERROR);
    }

    /**
     * 未经过身份认证
     * @param <T> 返回值类型
     * @return
     */
    public static <T> AjaxResult<T> authError(T data){
        return new AjaxResult<T>(ResultCode.AUTH_ERROR,data);
    }

    /**
     * 资源不存在
     * @param <T> 返回值类型
     * @return
     */
    public static <T> AjaxResult<T> error404(){
        return new AjaxResult<T>(ResultCode.NOT_FOUND);
    }

    /**
     * 资源不存在
     *
     * @param <T> 返回值类型
     * @return
     */
    public static <T> AjaxResult<T> error404(T data) {
        return new AjaxResult<T>(ResultCode.NOT_FOUND, data);
    }


    /**
     * 资源不存在
     *
     * @param <T> 返回值类型
     * @return
     */
    public static <T> AjaxResult<T> error503() {
        return new AjaxResult<T>(ResultCode.RPC_ERROR);
    }

    /**
     * 资源不存在
     *
     * @param <T> 返回值类型
     * @return
     */
    public static <T> AjaxResult<T> error503(T data) {
        return new AjaxResult<T>(ResultCode.RPC_ERROR, data);
    }


    public int getCode() {
        return code;
    }

    public String getMessage() {
        return message;
    }

    public T getData() {
        return data;
    }
}

②.返回封装类对应的Code类

/**
 * 状态处理
 * @author zeng
 */

public enum ResultCode {


    /**
     * 操作成功
     */
    SUCCESS(200, "操作成功"),
    /**
     * 操作失败
     */
    ERROR(400, "操作失败"),
    /**
     * 未经过身份认证
     */
    AUTH_ERROR(401, "未经过身份认证"),
    /**
     * 资源不存在
     */
    NOT_FOUND(404, "资源不存在"),
    /**
     * 服务器异常,请稍后再试
     */
    SYSTEM_ERROR(500, "服务器异常,请稍后再试"),
//    /**
//     * 用户信息解析异常,请稍后再试
//     */
//    USERPRINCIPAL_RESOLVER_ERROR(50001, "用户信息解析异常,请稍后再试"),
    /**
     * RPC或其他项目通信调用异常，外部服务异常
     */
    RPC_ERROR(503, "外部服务异常"),

    ;




    private final int code;
    private final String msg;

    ResultCode(int code, String msg) {
        this.code = code;
        this.msg = msg;
    }


    public int getCode() {
        return code;
    }

    public String getMsg() {
        return msg;
    }
}

④.vo返回前端类

/**
 * @author zeng
 * @date 21/04/20
 */
@ApiModel(value = "用户接口VO类")
public class UserVO {
    @ApiModelProperty(value = "用户ID", example = "10", name = "type", required = true)
    private Integer id;
    @ApiModelProperty(value = "用户名称", example = "xiaoming", name = "type", required = false)
    private String name;
    @ApiModelProperty(value = "用户年龄", example = "18", name = "type", required = false)
    private String age;

    public Integer getId() {
        return id;
    }

    public void setId(Integer id) {
        this.id = id;
    }

    public String getName() {
        return name;
    }

    public void setName(String name) {
        this.name = name;
    }

    public String getAge() {
        return age;
    }

    public void setAge(String age) {
        this.age = age;
    }

    @Override
    public String toString() {
        return "UserDTO{" +
                "id=" + id +
                ", name='" + name + '\'' +
                ", age='" + age + '\'' +
                '}';
    }
}

⑤.dto接收参数类

/**
 * @author zeng
 * @date 21/04/20
 */
@ApiModel(value = "用户接口DTO类")
public class UserDTO {
    @ApiModelProperty(value = "用户ID", example = "10", name = "id", required = true)
    private Integer id;
    @ApiModelProperty(value = "用户名称",name="name", example = "xiaoming", required = false)
    private String name;
    @ApiModelProperty(value = "用户年龄", example = "18", name = "age", required = false)

    public Integer getId() {
        return id;
    }

    public void setId(Integer id) {
        this.id = id;
    }

    public String getName() {
        return name;
    }

    public void setName(String name) {
        this.name = name;
    }

    public String getAge() {
        return age;
    }

    public void setAge(String age) {
        this.age = age;
    }

    @Override
    public String toString() {
        return "UserDTO{" +
                "id=" + id +
                ", name='" + name + '\'' +
                ", age='" + age + '\'' +
                '}';
    }
}

目前所有的类已经添加完成
效果图：