swagger不会用？统一返回值不会耍？天天和前端扯皮？？

共计 5108 个字符，预计需要花费 13 分钟才能阅读完成。

本文将展示如何使用swagger在线文档，后端接口统一返回值，请求参数校验，全局异常捕获等。

1.老生常谈，先新建springboot应用

引入相关依赖后pom如下

<properties>
    <java.version>1.8</java.version>
    <springfox.version>3.0.0</springfox.version>
    <hutool-all.version>5.7.15</hutool-all.version>
</properties>
<dependencies>
    <dependency>
        <groupId>org.springframework.boot</groupId>
        <artifactId>spring-boot-starter-validation</artifactId>
    </dependency>
    <dependency>
        <groupId>org.springframework.boot</groupId>
        <artifactId>spring-boot-starter-web</artifactId>
    </dependency>

    <dependency>
        <groupId>io.springfox</groupId>
        <artifactId>springfox-swagger2</artifactId>
        <version>${springfox.version}</version>
    </dependency>
    <dependency>
        <groupId>io.springfox</groupId>
        <artifactId>springfox-swagger-ui</artifactId>
        <version>${springfox.version}</version>
    </dependency>
    <dependency>
        <groupId>io.springfox</groupId>
        <artifactId>springfox-bean-validators</artifactId>
        <version>${springfox.version}</version>
    </dependency>
    <dependency>
        <groupId>io.springfox</groupId>
        <artifactId>springfox-data-rest</artifactId>
        <version>${springfox.version}</version>
    </dependency>
    <dependency>
        <groupId>io.springfox</groupId>
        <artifactId>springfox-oas</artifactId>
        <version>${springfox.version}</version>
    </dependency>
    <dependency>
        <groupId>cn.hutool</groupId>
        <artifactId>hutool-all</artifactId>
        <version>${hutool-all.version}</version>
    </dependency>

    <dependency>
        <groupId>org.springframework.boot</groupId>
        <artifactId>spring-boot-devtools</artifactId>
        <scope>runtime</scope>
        <optional>true</optional>
    </dependency>
    <dependency>
        <groupId>org.springframework.boot</groupId>
        <artifactId>spring-boot-configuration-processor</artifactId>
        <optional>true</optional>
    </dependency>
    <dependency>
        <groupId>org.projectlombok</groupId>
        <artifactId>lombok</artifactId>
        <optional>true</optional>
    </dependency>
    <dependency>
        <groupId>org.springframework.boot</groupId>
        <artifactId>spring-boot-starter-test</artifactId>
        <scope>test</scope>
    </dependency>
</dependencies>

<build>
    <plugins>
        <plugin>
            <groupId>org.springframework.boot</groupId>
            <artifactId>spring-boot-maven-plugin</artifactId>
            <configuration>
                <excludes>
                    <exclude>
                        <groupId>org.projectlombok</groupId>
                        <artifactId>lombok</artifactId>
                    </exclude>
                </excludes>
            </configuration>
        </plugin>
    </plugins>
</build>

2.swagger配置

笔者引用的是springfox的实现，但是开源老哥已经一年多没更新了

虽然提供了starter但是对笔者这种喜欢定制的人来说不够灵活

于是就有了上面的pom。

首先我们新建一个定制属性类

接着是核心配置

spring配置文件添加

至此swagger配置部分完成。到这很多小伙伴基本还是耍不了，毕竟代码都没贴全乎 没关系，最后会有完整样例。

3.全局异常配置

如下

@ControllerAdvice
public static class GlobalExceptionHandler {

    @ExceptionHandler(value = {ConstraintViolationException.class, MethodArgumentNotValidException.class, BindException.class,
            MethodArgumentTypeMismatchException.class, MissingServletRequestParameterException.class, HttpMessageNotReadableException.class,
            MissingServletRequestPartException.class})
    @ResponseBody
    public <T> CommonResult<T> handleValidationException(Exception e) {
        if (e instanceof ConstraintViolationException) {
            ConstraintViolationException constraintViolationException = (ConstraintViolationException) e;
            for (ConstraintViolation<?> constraintViolation : constraintViolationException.getConstraintViolations()) {
                return CommonResult.badRequest(constraintViolation.getMessage());
            }
        } else if (e instanceof MethodArgumentNotValidException) {
            MethodArgumentNotValidException methodArgumentNotValidException = (MethodArgumentNotValidException) e;
            BindingResult bindingResult = methodArgumentNotValidException.getBindingResult();
            for (ObjectError error : bindingResult.getAllErrors()) {
                return CommonResult.badRequest(error.getDefaultMessage());
            }
        } else if (e instanceof BindException) {
            BindException bindException = (BindException) e;
            BindingResult bindingResult = bindException.getBindingResult();
            for (ObjectError error : bindingResult.getAllErrors()) {
                return CommonResult.badRequest(error.getDefaultMessage());
            }
        } else if (e instanceof MissingServletRequestParameterException) {
            MissingServletRequestParameterException missingServletRequestParameterException = (MissingServletRequestParameterException) e;
            return CommonResult.badRequest(missingServletRequestParameterException.getParameterName() + "\nmiss");
        }
        return CommonResult.badRequest();
    }

    @ExceptionHandler(value = {HttpRequestMethodNotSupportedException.class})
    @ResponseBody
    public <T> CommonResult<T> handleNotSupportedException() {
        return CommonResult.result(HttpStatus.METHOD_NOT_ALLOWED.value(), HttpStatus.METHOD_NOT_ALLOWED.name());
    }

    @ExceptionHandler(value = Exception.class)
    @ResponseBody
    public <T> CommonResult<T> handleUnknownException() {
        return CommonResult.failed();
    }
}

4.发布接口

@Tag(name = "样例服务接口",description = "服务接口样例")
@RestController
@RequiredArgsConstructor
@Validated
@RequestMapping(value = "/api/sample")
public class SampleController {

    @Operation(summary = "传入id",tags = "样例服务接口")
    @GetMapping(value = "/get")
    public CommonResult<Integer> get(@Parameter(description = "传入id") @NotNull @Min(value = 18)@RequestParam(value = "id") Integer id) {
        return CommonResult.ok(id);
    }

    @Operation(summary = "添加用户",tags = "样例服务接口")
    @PutMapping(value = "/put")
    public CommonResult<User> put(@io.swagger.v3.oas.annotations.parameters.RequestBody @Validated(value = ValidationGroup.SubGroup1.class)@RequestBody User user) {
        return CommonResult.ok(user);
    }
}

这里接口就开启了参数校验，同时swagger上也能看到这些接口。

5.完整样例

https://github.com/flmelody/rest-swagger-sample

最终swagger效果

6.结束语
本文涉及内容，笔者只做了简略描述，注重于培养读者自己的思考能力以及探索能力，谢谢大家。