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

关注
发布于: 2020 年 11 月 19 日
一，整合Swagger3.0随着Spring Boot、Spring Cloud等微服务的流行，在微服务的设计下，小公司微服务工程jar小的几十个，大公司大的工程拆分jar多则几百上万个，这么多的微服务必定产生了大量的接口调用。而接口的调用就必定要写接口文档（由开发人员编写）。
存在的问题：（面对多个开发人员或多个开发团队）
项目开发接口众多，细节，复杂，且多样化，高质量地创建接口文档费时，费力。
随着项目的进行，不可避免整改和优化，需要不断的修改接口实现，伴随着也需要同时修改接口文档，管理不方便不说，还容易出现不一致的情况。
概述Swagger 是一个规范和完整的框架，用于生成、描述、调用和可视化 RESTful 风格的 Web 服务。
实际开发过程中Swagger 能够完美地与Spring Boot程序整合，组织出强大RESTful API文档，它既可以减少我们创建文档的工作量，同时也整合了说明内容在实现代码中，让维护文档和修改代码融为一体，可以让我们在修改代码逻辑的同时方便的修改文档说明。另外Swagger2还提供了强大的页面测试功能，让开发者能快速地调试每个RESTful API。
整合实现1，引入pom依赖。Swagger3.0的更新还是有很大变化的（详情参考），首先在依赖jar问题上，它新增了springfox-boot-starter，修复了2.x版本的冲突，移除了guava。另外Swagger3.0还移除了注解@EnableSwagger2，增加注解@EnableOpenApi。
 <!-- SpringBoot整合springfox-swagger3 -->
<dependency>
    <groupId>io.springfox</groupId>
    <artifactId>springfox-boot-starter</artifactId>
    <version>3.0.0</version>
</dependency>
        
启动SpringBoot主程序，可以直接测试访问：
需要注意的是，Swagger3.0还更新了UI页面地址，如上，而Swagger2.x的访问地址是这样的：http://localhost:8080/swagger-ui.html
﻿
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工程，测试访问　　注意：Swagger2.x版本不一样哦！关于2.x的配置版本也有些不同，这里就不介绍了...
﻿
二，统一接口返回值我们在应用中经常会涉及到 server 和 client 的交互，目前比较流行的是基于 json 格式的数据交互。但是 json 只是消息的格式，其中的内容还需要我们自行设计。不管是 HTTP 接口还是 RPC 接口保持返回值格式统一很重要，这将大大降低 client 的开发成本。
一般定义Response的标准格式包含四部分：
Integer code ；成功时返回 0 ，失败时返回具体错误码。（可以自定义错误码，使用枚举类封装）
String message ；成功时返回 null ，失败时返回具体错误消息。（可以自定义错误消息，使用枚举类封装）
T data ；成功时具体返回值，失败时为 null 。
例如：
{
   "code": 0,
   "messages": "",
   "data": ""
}
定义枚举类，封装状态码和消息定义一些常见的成功与失败的枚举常量。如下：（该枚举类可以作为工具使用了，有心的朋友可自行保存一下）
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;
   }
}
定义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 有失败状态码，描述，没有结果集数据的标准格式对象
    */
   public static<T>  ResponseData<T> error(EnumCode enumCode) {
       // 创建响应标准格式对象
       ResponseData<T> responseData = new ResponseData<T>();
       // 调用转换器方法，将（错误）枚举常量解析。
       responseData.parserEnum(enumCode);
       return responseData;
   }

   /** 有成功，有失败，但是失败的状态描述不一定能全部满足需求（枚举类有限），所以，自定义方法实现自定义信息
    * @param code 自定义的状态码
    * @param message  自定义的错误信息
    * @return  有失败自定义状态码，自定义描述，没有结果集数据的标准格式对象
    */
    public static<T> ResponseData<T> generator(int code,String message) {
       // 创建响应标准格式对象
       ResponseData<T> responseData = new ResponseData<T>();
       responseData.setCode(code);
       responseData.setMessage(message);
       return responseData;
   }

}
温馨提示：静态方法定义泛型时，必须使用statc<T>定义，否则编译失败。
解惑：有人可能存在疑问，既然枚举类不能满足所有响应要求，干嘛定义枚举类，感觉有点多此一举！直接自定义封装多好，可以解决所有问题。但是，请记住，团队开发，如果全部使用自定义封装，那么如何实现信息的统一标准呢？当出现同一个错误时，有人提示系统错误，有人提示后台错误，有人提示请联系管理员？？？这样是不是很乱。所以常见的，基本的消息定义，通过枚举类列举，可以轻松实现统一管理。而不常见的错误，既然不常见，那么又怎可能经常自定义？这就是简易的架构设计优化。
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;
   }
   
}
打开浏览器测试访问。
Postman测试访问：（输入接口URL，传递参数测试即可）
﻿
测试结果如下：
﻿
发布于: 2020 年 11 月 19 日阅读数: 101
比伯

关注
还未添加个人签名 2020.11.09 加入
还未添加个人简介
发布
暂无评论
创作场景

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

一，整合Swagger3.0

概述

1.整合实现

1，引入pom依赖。

2，自定义SwaggerConfig类

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

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

二，统一接口返回值

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

2.定义Response的标准格式POJO

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

比伯

评论

创作场景

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

一，整合Swagger3.0

概述

1.整合实现

1，引入pom依赖。

2，自定义SwaggerConfig类

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

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

二，统一接口返回值

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

2.定义Response的标准格式POJO

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

比伯

评论

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