*swagger接口可视化文档

springboot的 swagger接口可视化文档 配置。

一、依赖

<!--接口可视化文档依赖-->
<dependency>
     <groupId>com.github.xiaoymin</groupId>
     <artifactId>knife4j-spring-boot-starter</artifactId>
     <version>2.0.2</version>
</dependency>

<!--注解校验-->
<dependency>
      <groupId>org.springframework.boot</groupId>
      <artifactId>spring-boot-starter-validation</artifactId>
</dependency>

二、示例

（2.1）@Api 和 @ApiOperation 声明 接口名称

package com.test.controller;

import com.test.base.Result;
import io.swagger.annotations.Api;
import io.swagger.annotations.ApiOperation;
import org.springframework.beans.factory.annotation.Autowired;
import org.springframework.web.bind.annotation.PathVariable;
import org.springframework.web.bind.annotation.PostMapping;
import org.springframework.web.bind.annotation.RequestMapping;
import org.springframework.web.bind.annotation.RestController;


@Api(tags = "用户管理")  // 接口所在目录名称
@RestController
@RequestMapping("/v1/user")
public class UserController {

    @Autowired
    UserService userService;
    
    @ApiOperation(value = "添加用户") // 接口名称
    @PostMapping("/add")
    public Result<UserVO> add(@Validated @RequestBody UserBO bo) {
        return Result.ok(userService.add(bo));
    }

}

（2.2）接口返回类 声明 接口 返回 数据结构

package com.test.base;


import lombok.Data;

/**
 * @description: 返回，必须要有T泛型，不然swagger不会显示返回的数据结构
 * @author: wuguixin
 * @create: 2022-03-08 17:05
 **/
@Data
public class Result<T> {
    private Integer code;
    private String msg;
    private T data;

    public Result(Integer code, String msg, T data) {
        this.code = code;
        this.msg = msg;
        this.data = data;
    }

    public Result(Integer code, String msg) {
        this.code = code;
        this.msg = msg;
    }

    public static<T> Result<T> ok(T data) {
        return new Result(0, "成功", data);
    }

    public static<T> Result<T> err(String msg) {
        return new Result(1, msg);
    }

    public static<T> Result<T> err(Exception e) {
        return new Result(1, e.getMessage());
    }
}

（2.3）@ApiModelProperty 声明  接口 返回 数据结构

package com.test.entity.vo;

import com.fasterxml.jackson.annotation.JsonFormat;
import io.swagger.annotations.ApiModelProperty;
import lombok.Data;
import lombok.experimental.Accessors;
import java.io.Serializable;
import java.time.LocalDateTime;


@Data
@Accessors(chain = true)
public class UserVO implements Serializable {

    @ApiModelProperty(value="用户名称")
    private String userName;

    @ApiModelProperty(value="用户id")
    private String userId;

    @JsonFormat(pattern = "yyyy-MM-dd HH:mm:ss")
    @ApiModelProperty(value="创建时间")
    private LocalDateTime createTime;

    @JsonFormat(pattern = "yyyy-MM-dd HH:mm:ss")
    @ApiModelProperty(value="更新时间")
    private LocalDateTime updateTime;
}

（2.3）@ApiModelProperty 声明  接口 参数

package com.test.entity.user.bo;

import io.swagger.annotations.ApiModelProperty;
import javax.validation.constraints.NotBlank;

// UserAddBO这个名称不能有重复，不然 swagger 会默认只显示第一个UserAddBO，而不会显示第二个UserAddBO
@Data
public class UserAddBO {

    @NotBlank(message = "用户名称必填")
    @ApiModelProperty(value="用户名称",required = true)
    private String userName;

}

（2.4）

package com.test.config;

import com.test.base.Result;
import org.springframework.web.bind.MethodArgumentNotValidException;
import org.springframework.web.bind.annotation.ControllerAdvice;
import org.springframework.web.bind.annotation.ExceptionHandler;
import org.springframework.web.bind.annotation.ResponseBody;

import javax.validation.ConstraintViolationException;

/**
 * ‘@validated注解‘ 参数校验 异常捕获
 */
@Slf4j
@ControllerAdvice
public class ValidatedExceptionHandler {
    private Logger log = LoggerFactory.getLogger(this.getClass());

    @ExceptionHandler(Exception.class)
    @ResponseBody
    public Result exception(Exception e) {
        log.error("全局异常捕获", e);
        return Result.err(e);
    }

    @ExceptionHandler(MethodArgumentNotValidException.class)
    @ResponseBody
    public Result methodArgumentNotValidException(MethodArgumentNotValidException e){
        log.error("validate异常", e);
        return Result.err(e.getBindingResult().getFieldError().getDefaultMessage());
    }

    @ExceptionHandler(ConstraintViolationException.class)
    @ResponseBody
    public Result constraintViolationException(ConstraintViolationException e){
        log.error("validate异常", e);
        return Result.err(e.getLocalizedMessage());
    }

    @ExceptionHandler(IllegalArgumentException.class)
    @ResponseBody
    public Result illegalArgumentException(IllegalArgumentException e){
        log.error("不合法参数异常", e);
        return Result.err(e.getMessage());
    }

}