SpringBoot：整合Swagger3.0-定制RESTful与统一接口返回值（2020最新最易懂）

我会带着你远行 2022-09-04 02:57 141阅读 0赞

# 一，整合Swagger3.0 #

随着Spring Boot、Spring Cloud等微服务的流行，在微服务的设计下，小公司微服务工程jar小的几十个，大公司大的工程拆分jar多则几百上万个，这么多的微服务必定产生了大量的接口调用。而接口的调用就必定要写接口文档（由开发人员编写）。

存在的问题：（面对多个开发人员或多个开发团队）

项目开发接口众多，细节，复杂，且多样化，高质量地创建接口文档费时，费力。  
随着项目的进行，不可避免整改和优化，需要不断的修改接口实现，伴随着也需要同时修改接口文档，管理不方便不说，还容易出现不一致的情况。

## 概述 ##

Swagger 是一个规范和完整的框架，用于生成、描述、调用和可视化 RESTful 风格的 Web 服务。

实际开发过程中Swagger 能够完美的与Spring Boot程序整合，组织出强大RESTful API文档，它既可以减少我们创建文档的工作量，同时也整合了说明内容在实现代码中，让维护文档和修改代码融为一体，可以让我们在修改代码逻辑的同时方便的修改文档说明。另外Swagger2还提供了强大的页面测试功能，让开发者能快速的调试每个RESTful API。

# 1.整合实现 #

## 1，引入pom依赖 ##

Swagger3.0的更新还是有很大变化的（详情参考），首先在依赖jar问题上，它新增了springfox-boot-starter，修复了2.x版本的冲突，移除了guava。另外Swagger3.0还移除了注解@EnableSwagger2，增加注解==@EnableOpenApi==。

<dependency>
        <groupId>io.springfox</groupId>
        <artifactId>springfox-boot-starter</artifactId>
        <version>3.0.0</version>
    </dependency>

启动SpringBoot主程序，可以直接测试访问：

测试地址：http://localhost:8080/swagger-ui/index.html （访问后提供的有默认的错误调用接口文档）

需要注意的是，Swagger3.0还更新了UI页面地址，如上，而Swagger2.x的访问地址是这样的：http://localhost:8080/swagger-ui.html

![在这里插入图片描述][watermark_type_ZmFuZ3poZW5naGVpdGk_shadow_10_text_aHR0cHM6Ly9ibG9nLmNzZG4ubmV0L3dlaXhpbl80NDA5NjM1Mw_size_16_color_FFFFFF_t_70_pic_center]

## 2，自定义SwaggerConfig类 ##

新增SwaggerConfig类，并将其加载到Spring IOC中。需要注意：自定义Swagger配置类，Swagger3.0移除注解@EnableSwagger2，增加注解  
　　@EnableOpenApi。@EnableOpenApi可以在Config类中应用，也可以在SpringBoot主启动类上使用（选其一即可），表示启用自定义API接口。

@EnableOpenApi   // 开启Swagger自定义接口文档
    @Configuration   // 相当于Spring配置中的<beans>
    public class SwaggerConfig { 
        @Bean   // 相当于Spring 配置中的<bean>
        public Docket createRestApi() { 
            return new Docket(DocumentationType.OAS_30)
                    .apiInfo(apiInfo())
                    .select()
                    .apis(RequestHandlerSelectors.withMethodAnnotation(ApiOperation.class))
                    .paths(PathSelectors.any())
                    .build();
        }
        // API基础信息定义（就是更新Swagger默认页面上的信息）
        private ApiInfo apiInfo() { 
            return new ApiInfoBuilder()
                    .title("Swagger3接口文档测试")
                    .description("文档描述：更多问题，请联系开发者")
                    .contact(new Contact("xsge123（name）", "作者网站(url)", "1511868921@qq.com(email)"))
                    .version("1.0")
                    .build();
        }
    
    }

## 3，编写Controller提供RESTful风格的接口API ##

编写Controller前，先看看一些注解的意思吧！

@Api：用在控制器类上，表示对类的说明
        tags="说明该类的作用，可以在UI界面上看到的说明信息的一个好用注解"
        value="该参数没什么意义，在UI界面上也看到，所以不需要配置"
    
    @ApiOperation：用在请求的方法上，说明方法的用途、作用
        value="说明方法的用途、作用"
        notes="方法的备注说明"
    
    @ApiImplicitParams：用在请求的方法上，表示一组参数说明
        @ApiImplicitParam：用在@ApiImplicitParams注解中，指定一个请求参数的各个方面（标注一个指定的参数，详细概括参数的各个方面，例如：参数名是什么？参数意义，是否必填等）
            name：属性值为方法参数名
            value：参数意义的汉字说明、解释
            required：参数是否必须传
            paramType：参数放在哪个地方
                · header --> 请求参数的获取：@RequestHeader
                · query --> 请求参数的获取：@RequestParam
                · path（用于restful接口）--> 请求参数的获取：@PathVariable
                · div（不常用）
                · form（不常用）    
            dataType：参数类型，默认String，其它值dataType="Integer"       
            defaultValue：参数的默认值
    
    @ApiResponses：用在请求的方法上，表示一组响应
        @ApiResponse：用在@ApiResponses中，一般用于表达一个错误的响应信息
            code：状态码数字，例如400
            message：信息，例如"请求参数没填好"
            response：抛出异常的类
    
    @ApiModel：用于响应类上（POJO实体类），描述一个返回响应数据的信息（描述POJO类请求或响应的实体说明）
                （这种一般用在post接口的时候，使用@RequestBody接收JSON格式的数据的场景，请求参数无法使用@ApiImplicitParam注解进行描述的时候）
        @ApiModelProperty：用在POJO属性上，描述响应类的属性说明
    @ApiIgnore：使用该注解忽略这个API；

Spring Boot中包含了一些控制器方法RESTful接口注解，对应于HTTP协议中的方法：

*  @GetMapping对应HTTP中的GET方法；
 *  @PostMapping对应HTTP中的POST方法；
 *  @PutMapping对应HTTP中的PUT方法；
 *  @DeleteMapping对应HTTP中的DELETE方法；
 *  @PatchMapping对应HTTP中的PATCH方法。

@Api(value = "测试SwaggerAPI Annotation", tags = "Swagger测试之用户信息管理API")
    @RestController
    @RequestMapping("/user")
    public class SwaggerController { 
    
        @ApiIgnore    // 忽略这个API
        @GetMapping("/hello")
        public String hello() { 
            return "hello";
        }
    
        @GetMapping(value = "/swaggerGet/{name}")
        @ApiOperation(value = "接口方法说明", notes = "接口的详情描述")
        @ApiImplicitParam(name = "name", value = "请传递一个用户名参数",required = true, dataType = "String", paramType = "path")
        public String swaggerGet(@PathVariable  String name) { 
            return "name="+name;
        }
    
        @PostMapping(value = "/swaggerPost")
        @ApiOperation(value = "新增用户", notes = "Swagger测试RESTful之POST请求测试入参一个POJO（JSON格式）")
        public User swaggerGet(@RequestBody User user) { 
            return user;
        }
    
    }

实体类

@ApiModel("用户信息实体类")
    @Data
    public class User { 
        // example:示例代码值
        @ApiModelProperty(value = "用户名",dataType="String",name="username",example="xsge")
        private String username;
        @ApiModelProperty(value = "账户密码",dataType="String",name="password",example="123456")
        private String password;
    
    }

## 4，启动SpringBoot工程，测试访问 ##

输入地址：http://localhost:8080/swagger-ui/index.html 进入Swagger接口文档界面。

注意：Swagger2.x版本不一样哦！关于2.x的配置版本也有些不同，这里就不介绍了…

![在这里插入图片描述][watermark_type_ZmFuZ3poZW5naGVpdGk_shadow_10_text_aHR0cHM6Ly9ibG9nLmNzZG4ubmV0L3dlaXhpbl80NDA5NjM1Mw_size_16_color_FFFFFF_t_70_pic_center 1]

# 二，统一接口返回值 #

我们在应用中经常会涉及到 server 和 client 的交互，目前比较流行的是基于 json 格式的数据交互。但是 json 只是消息的格式，其中的内容还需要我们自行设计。不管是 HTTP 接口还是 RPC 接口保持返回值格式统一很重要，这将大大降低 client 的开发成本。

一般定义Response的标准格式包含四部分：

*  Integer code ；成功时返回 0 ，失败时返回具体错误码。（可以自定义错误码，使用枚举类封装）
 *  String message ；成功时返回 null ，失败时返回具体错误消息。（可以自定义错误消息，使用枚举类封装）
 *  T data ；成功时具体返回值，失败时为 null 。

例如：

{
         "code": 0,
         "messages": "",
         "data": ""
     }

## 1.定义枚举类，封装状态码和消息 ##

定义一些常见的成功与失败的枚举常量。如下：（该枚举类可以作为工具使用了，有心的朋友可自行保存一下）

public enum EnumCode { 
        // 定义成功的枚举常量，状态码，和描述
        SUCCESS(0,"ok"),// 这里的代码相当于：public static final DataEnumCode SUCCESS = new DataEnumCode(0,“ok”)调用类有参构造传值
        // 定义系统异常的枚举常量，状态码，和描述
        SYSTEM_ERROR(5001,"服务器系统异常，请稍后..."),
        // 定义参数异常的枚举常量，状态码，和描述
        PARAMETER_ERROR(5002,"参数异常，认证失败..."),
        // 定义用户名存在异常的枚举常量，状态码，和描述
        USER_HAS_ERROR(5003,"用户名已存在....");// 注意上面的是逗号分隔，这里结束是分号
    
        // 定义的枚举常量属性。
        private int code;// 状态码
        private String message;// 描述
    
        /** * 私有构造,防止被外部调用 */
        private EnumCode(int code, String message) { 
            this.code = code;
            this.message = message;
        }
         /** * 定义方法,返回描述,跟常规类的定义get没区别 * @return */
        public int getCode() { 
            return code;
        }
        public String getMessage() { 
            return message;
        }
    }

## 2.定义Response的标准格式POJO ##

为便于合理化实现标准格式的响应，新增POJO类，并添加封装属性（状态码，描述信息，响应数据）。

为便于标准化的实施，类中提供的如下四个方法：（该解析响应类可以作为工具使用了，有心的朋友可自行保存一下）

*  成功方法。请求成功，响应结果集数据，响应状态码，描述，状态码和描述从枚举常量中解析。
 *  失败方法。请求失败，无结果集数据，响应状态码，描述保留，状态码和描述从枚举常量中解析。（枚举类型有限，不一定满足所有异常）
 *  失败方法。请求失败，无结果集数据，响应状态码，描述保留，该方法用于解决因为枚举常量的局限性，不足以满足所有需求的问题，实现允许自定义状态码和描述。
 *  提供便于解析枚举常量的方法。

@Data
    @NoArgsConstructor
    @AllArgsConstructor
    public class ResponseData<T>{ 
    
        private int code;// 状态码
        private String message;// 提示消息
        private T data;// 响应结果集数据
    
        /**枚举类常量解析器 * 快速解析枚举类常量信息，解析数据并放入到标准响应类ResponseData的属性中 * @param enumCode */
        public void parserEnum(EnumCode enumCode) { 
            this.code = enumCode.getCode();// 获取枚举常量的状态码，赋值给属性
            this.message = enumCode.getMessage();// 获取枚举常量的描述信息
        }
    
        /**定义请求成功的：状态码，描述，结果集数据 * @param data 传递的响应结果集数据 * @return 有成功状态码，描述，结果集数据的标准格式对象 */
        public static<T> ResponseData<T> success(T data) { 
            // 创建响应标准格式对象
            ResponseData<T> responseData = new ResponseData<T>();
            // 调用转换器方法，将（成功）枚举常量解析，放入到标准响应数据中。
            responseData.parserEnum(EnumCode.SUCCESS);
            // 放入响应数据
            responseData.setData(data);
            return responseData;
        }
    
    
        /**定义请求失败的： * @param enumCode 失败时传递的常见错误枚举常量 * @return 有失败状态码，描述，结果集可为null，也可为自定义异常信息 */
        public static<T>  ResponseData<T> error(EnumCode enumCode,T data) { 
            // 创建响应标准格式对象
            ResponseData<T> responseData = new ResponseData<T>();
            // 调用转换器方法，将（错误）枚举常量解析。
            responseData.parserEnum(enumCode);
            responseData.setData(data);
            return responseData;
        }
    
        /** 有成功，有失败，但是失败的状态描述不一定能全部满足需求（枚举类有限），所以，自定义方法实现自定义信息 * @param code 自定义的状态码 * @param message 自定义的错误信息 * @return 有失败自定义状态码，自定义描述，结果集可为null，也可为自定义异常信息 */
         public static<T> ResponseData<T> generator(int code,String message,T data) { 
            // 创建响应标准格式对象
            ResponseData<T> responseData = new ResponseData<T>();
            responseData.setCode(code);
            responseData.setMessage(message);
            responseData.setData(data);
            return responseData;
        }
    
    }

温馨提示：静态方法定义泛型时，必须使用statc定义，否则编译失败。

> 解惑：有人可能存在疑问，既然枚举类不能满足所有响应要求，干嘛定义枚举类，感觉有点多此一举！直接自定义封装多好，可以解决所有问题。但是，请记住，团队开发，如果全部使用自定义封装，那么如何实现信息的统一标准呢？当出现同一个错误时，有人提示系统错误，有人提示后台错误，有人提示请联系管理员？？？这样是不是很乱。所以常见的，基本的消息定义，通过枚举类列举，可以轻松实现统一管理。而不常见的错误，既然不常见，那么又怎可能经常自定义？这就是简易的架构设计优化。

## 3， 编写Controller提供RESTful风格接口 ##

@Api(value = "测试SwaggerAPI Annotation", tags = "Swagger测试之用户信息管理API")
    @RestController
    @RequestMapping("/user")
    public class SwaggerController { 
    
        @ApiIgnore    // 忽略这个API
        @GetMapping("/hello")
        public String hello() { 
            return "hello";
        }
    
        @GetMapping(value = "/swaggerGet/{name}")
        @ApiOperation(value = "接口方法说明", notes = "接口的详情描述")
        @ApiImplicitParam(name = "name", value = "请传递一个用户名参数",required = false,dataType = "String", paramType = "path")
        public ResponseData<String> swaggerGet(@PathVariable String name) { 
            // 调用成功的解析方法，并传递响应数据
            ResponseData<String> responseData = ResponseData.success(name);
            return responseData;
        }
    
        @PostMapping(value = "/swaggerPost")
        @ApiOperation(value = "新增用户", notes = "Swagger测试RESTful之POST请求测试入参一个POJO（JSON格式）")
        public ResponseData<User> swaggerGet(@RequestBody User user) { 
            // 调用成功的解析方法，并传递响应数据
            ResponseData<User> responseData = ResponseData.success(user);
            return responseData;
        }
    
    }

4.打开浏览器测试访问。

浏览器测试访问：http://localhost:8080/swagger-ui/index.html （选择测试一下，按照接口文档说明实施测试）

Postman测试访问：（输入接口URL，传递参数测试即可）

![在这里插入图片描述][watermark_type_ZmFuZ3poZW5naGVpdGk_shadow_10_text_aHR0cHM6Ly9ibG9nLmNzZG4ubmV0L3dlaXhpbl80NDA5NjM1Mw_size_16_color_FFFFFF_t_70_pic_center 2]  
结果如下：

![在这里插入图片描述][watermark_type_ZmFuZ3poZW5naGVpdGk_shadow_10_text_aHR0cHM6Ly9ibG9nLmNzZG4ubmV0L3dlaXhpbl80NDA5NjM1Mw_size_16_color_FFFFFF_t_70_pic_center 3]

# 三，统一返回值高级处理方式 #

## 1.统一返回值标准格式存在的问题 ##

A：控制器方法返回值普遍需要变动类型为ResponseData，不灵活。

B：方法返回数据前都必须有一段包装代码，最后返回ResponseData。（代码啰嗦，不实用）

## 2.解决方案 ##

ResponseBodyAdvice接口，是SpringBoot提供的拦截Controller方法返回值的处理器增强类。

ResponseBodyAdvice的主要作用：拦截Controller方法的返回值，统一处理返回值/响应体，一般用来做response的统一格式、加解密、签名等

## 3.实现方案 ##

在上面代码统一标准结果的基础上实现：保留枚举类，和统一结果集POJO类，而后继续：

1.  编写普通类实现接口ResponseBodyAdvice 接口中含有两个方法：  
    beforeBodyWrite：返回值增强处理方法。  
    supports: 是否拦截控制器方法返回值，执行返回值增强。
2.  修改方法supports返回值为true。
3.  修改方法beforeBodyWrite，添加代码如下
4.  类上采用注解（切记不要省略属性basePackages）  
    @RestControllerAdvice(basePackages =“com.xsge123.app”)

// @ControllerAdvice：作用：对所有控制器中，被@RequestMapping注解标注的方法，进行增强（也可以直接使用@RestControllerAdvice）
    @RestControllerAdvice(basePackages  = "com.xsge123.app")   // 控制器类增强：可以对Controller中所有使用@RequestMapping注解的方法增强
    public class ResponseResult<T> implements ResponseBodyAdvice<Object>{ 
    
        /**被拦截的响应，立即执行该方法。 * body ：是请求控制器方法接口后，响应的内容。（其他参数不用了解） */
        @Override
        public Object beforeBodyWrite(Object body, MethodParameter returnType, MediaType selectedContentType,
                Class<? extends HttpMessageConverter<?>> selectedConverterType, ServerHttpRequest request,
                ServerHttpResponse response) { 
    
            // String类型不能直接包装
            if (returnType.getGenericParameterType().equals(String.class)) { 
                ObjectMapper objectMapper = new ObjectMapper();
                    // 将数据包装在ResultVo里后转换为json串进行返回
                try { 
                    return objectMapper.writeValueAsString(ResponseData.success(body));
                } catch (JsonProcessingException e) { 
                    // 这里正常应该加如自定义的统一异常处理
                    e.printStackTrace();
                }
            }
            -------------------------
            return ResponseData.success(body);
        }
    
        /** * 这个方法的返回值，决定是否启动结果响应拦截，当返回为true是，表示拦截 */
        @Override
        public boolean supports(MethodParameter returnType, Class<? extends HttpMessageConverter<?>> converterType) { 
            return true;
        }
    
    }

说明：

不要忘记添加注解：**@RestControllerAdvice（basePackages = “com.xsge123.app”）特别注意，这里不能省略basePackages属性，否则不生效**

@ControllerAdvice这是一个非常有用的注解，它的作用是增强Controller的扩展功能类（凡是控制器方法含有@RequestMapping注解的都会被执行增强指定功能）。

**@ControllerAdvice：作用：对所有控制器中，被@RequestMapping注解标注的方法，进行增强（也可以直接使用@RestControllerAdvice）**

**该注解主要的场景用于：  
1.增强异常处理的能力，实现异常统一处理。（该功能参数博主SpringBoot第七集统一异常处理）  
2.增强返回数据处理能力，实现返回统一格式的JSON数据。（当前正是介绍演示的这个功能）**

## 4.编写控制器，提供暴露接口 ##

控制器方法返回值更灵活了…

@Api(value = "测试SwaggerAPI Annotation", tags = "Swagger测试之人物信息管理API")
    @RestController
    @RequestMapping("/person")
    public class SwaggerControllerAdvice { 
    
    
        @GetMapping(value = "/{name}")
        @ApiOperation(value = "Adivc接口方法说明", notes = "接口的详情描述")
        @ApiImplicitParam(name = "name", value = "请传递一个用户名参数",required = false,dataType = "String", paramType = "path")
        public String swaggerGet(@PathVariable String name) { 
            return name;
        }
    
        @PostMapping(value = "/swaggerPost")
        @ApiOperation(value = "Adivc新增用户", notes = "Swagger测试RESTful之POST请求测试入参一个POJO（JSON格式）")
        public User swaggerGet(@RequestBody User user) { 
            return user;
        }
    
    }

温馨提示：控制注解使用的是@RestController。

## 5.访问SwagerUI，实施测试。 ##

访问地址：http://localhost:8080/swagger-ui/index.html

测试结果我这里就暂时略过了，我行，不中用，得你行才是真的行！

# 四，整合统一异常 #

问题：  
　　统一异常处理结果：

{
        "timestamp": "2020-11-23T09:32:55.365+00:00",
        "respCode": 0,
        "respMsg": "服务器刷新异常，请稍后。。。",
        "message": "/ by zero",
        "exceptionName": "java.lang.ArithmeticException",
        "path": "/queryPersonById/1",
        "data": null
    }

统一响应返回值结果：

{
        "code": 0,
        "message": "ok",
        "data": {
            "username": "xsge",
            "password": "2222"
        }
    }

返回数据格式存存在两种格式，既然统一，就应当全部统一（code，message，data）。因此需要深入处理，将异常处理也集成到统一响应格式中（统一格式的JSON）。

## 实现方式 ##

1.修改接口ResponseBodyAdvice实现类ResponseResult中方法beforeBodyWrite添加如下逻辑判断：

/**被拦截的响应，立即执行该方法。 * body ：是请求控制器方法接口后，响应的内容。（其他参数不用了解） */
        @Override
        public Object beforeBodyWrite(Object body, MethodParameter returnType, MediaType selectedContentType,
                Class<? extends HttpMessageConverter<?>> selectedConverterType, ServerHttpRequest request,
                ServerHttpResponse response) { 
            System.out.println(body);
            // String类型不能直接包装
            if (returnType.getGenericParameterType().equals(String.class)) { 
                ObjectMapper objectMapper = new ObjectMapper();
                    // 将数据包装在ResultVo里后转换为json串进行返回
                try { 
                    return objectMapper.writeValueAsString(ResponseData.success(body));
                } catch (JsonProcessingException e) { 
                    // 这里正常应该加如自定义的统一异常处理
                    e.printStackTrace();
                }
            // =============================================================
            } else if(body instanceof ExceptionResponseResult) { // 判断返回值结果是否是一个异常对象类型
                // 如果是异常类型，传入异常状态码（枚举类型）和异常数据。
                return ResponseData.error(EnumCode.SYSTEM_ERROR,body);
            }
            // =============================================================
            return ResponseData.success(body);
        }

2.测试  
　　访问接口：http://localhost:8080/person/swaggerPost  
　　入参：\{“username”: “xsge”,“password”: “2222”\}

@PostMapping(value = "/swaggerPost")
        @ApiOperation(value = "Adivc新增用户", notes = "Swagger测试RESTful之POST请求测试入参一个POJO（JSON格式）")
        public User swaggerGet(@RequestBody User user) { 
            int a = 10/0;
            return user;
        }

结果

{
        "code": 5001,
        "message": "服务器系统异常，请稍后...",
        "data": {
            "timestamp": "2020-11-23T12:05:55.794+00:00",
            "respMsg": "服务器刷新异常，请稍后。。。",
            "message": "/ by zero",
            "exceptionName": "java.lang.ArithmeticException",
            "path": "/person/swaggerPost"
        }
    }

如果在更改时，觉得消息过于复杂，有些又觉得没有用，可以自己定义修改类ExceptionResponseResult的属性即可。一句话根据自己需求定义！

--------------------

转自：[SpringBoot第十一集：整合Swagger3.0-定制RESTful与统一接口返回值（2020最新最易懂）][SpringBoot_Swagger3.0-_RESTful_2020]

[watermark_type_ZmFuZ3poZW5naGVpdGk_shadow_10_text_aHR0cHM6Ly9ibG9nLmNzZG4ubmV0L3dlaXhpbl80NDA5NjM1Mw_size_16_color_FFFFFF_t_70_pic_center]: /images/20220829/129533a42c1347b88ebf7c44d92d5b0b.png
[watermark_type_ZmFuZ3poZW5naGVpdGk_shadow_10_text_aHR0cHM6Ly9ibG9nLmNzZG4ubmV0L3dlaXhpbl80NDA5NjM1Mw_size_16_color_FFFFFF_t_70_pic_center 1]: /images/20220829/360227e061c8495a8603827ad3fdc795.png
[watermark_type_ZmFuZ3poZW5naGVpdGk_shadow_10_text_aHR0cHM6Ly9ibG9nLmNzZG4ubmV0L3dlaXhpbl80NDA5NjM1Mw_size_16_color_FFFFFF_t_70_pic_center 2]: /images/20220829/83c8010982d14448b5b30413d1f1aca3.png
[watermark_type_ZmFuZ3poZW5naGVpdGk_shadow_10_text_aHR0cHM6Ly9ibG9nLmNzZG4ubmV0L3dlaXhpbl80NDA5NjM1Mw_size_16_color_FFFFFF_t_70_pic_center 3]: /images/20220829/c9f671d390c843a490c9d4e176f7fd96.png
[SpringBoot_Swagger3.0-_RESTful_2020]: https://www.cnblogs.com/xsge/p/13996625.html