一，整合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。

1 <!-- SpringBoot整合springfox-swagger3 -->
2<dependency>
3    <groupId>io.springfox</groupId>
4    <artifactId>springfox-boot-starter</artifactId>
5    <version>3.0.0</version>
6</dependency>
7

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

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

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

SpringBoot整合Swagger与REST接口返回值

2，自定义SwaggerConfig类

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

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

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

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

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

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

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

1 @Api(value = "测试SwaggerAPI Annotation", tags = "Swagger测试之用户信息管理API") 2 @RestController 3 @RequestMapping("/user") 4 public class SwaggerController { 5
6 @ApiIgnore // 忽略这个API 7 @GetMapping("/hello") 8 public String hello() { 9 return "hello"; 10 } 11
12 @GetMapping(value = "/swaggerGet/{name}") 13 @ApiOperation(value = "接口方法说明", notes = "接口的详情描述") 14 @ApiImplicitParam(name = "name", value = "请传递一个用户名参数",required = true, dataType = "String", paramType = "path") 15 public String swaggerGet(@PathVariable String name) { 16 return "name="+name; 17 } 18
19 @PostMapping(value = "/swaggerPost") 20 @ApiOperation(value = "新增用户", notes = "Swagger测试RESTful之POST请求测试入参一个POJO（JSON格式）") 21 public User swaggerGet(@RequestBody User user) { 22 return user; 23 } 24
25 }

实体类

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

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

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

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

SpringBoot整合Swagger与REST接口返回值

二，统一接口返回值

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

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

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

例如：

11 {
22     "code": 0,
33     "messages": "",
44     "data": ""
55 }

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

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

1 1 public enum EnumCode {
2 2     // 定义成功的枚举常量，状态码，和描述
3 3     SUCCESS(0,"ok"),// 这里的代码相当于：public static  final DataEnumCode SUCCESS = new DataEnumCode(0,“ok”)调用类有参构造传值
4 4     // 定义系统异常的枚举常量，状态码，和描述
5 5     SYSTEM_ERROR(5001,"服务器系统异常，请稍后..."),
6 6     // 定义参数异常的枚举常量，状态码，和描述
7 7     PARAMETER_ERROR(5002,"参数异常，认证失败..."),
8 8     // 定义用户名存在异常的枚举常量，状态码，和描述
9 9     USER_HAS_ERROR(5003,"用户名已存在....");// 注意上面的是逗号分隔，这里结束是分号
1010     
1111     // 定义的枚举常量属性。
1212     private int code;// 状态码
1313     private String message;// 描述
1414     
1515     /**
1616      * 私有构造,防止被外部调用
1717      */
1818     private EnumCode(int code, String message) {
1919         this.code = code;
2020         this.message = message;
2121     }
2222      /**
2323      * 定义方法,返回描述,跟常规类的定义get没区别
2424      * @return
2525      */
2626     public int getCode() {
2727         return code;
2828     }
2929     public String getMessage() {
3030         return message;
3131     }
3232 }

2.定义Response的标准格式POJO

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

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

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

1 @Data 2 @NoArgsConstructor 3 @AllArgsConstructor 4 public class ResponseData<T> { 5 6 private int code;// 状态码 7 private String message;// 提示消息 8 private T data;// 响应结果集数据 9 10 /**枚举类常量解析器 11 * 快速解析枚举类常量信息，解析数据并放入到标准响应类ResponseData的属性中 12 * @param enumCode 13 */ 14 public void parserEnum(EnumCode enumCode) { 15 this.code = enumCode.getCode();// 获取枚举常量的状态码，赋值给属性 16 this.message = enumCode.getMessage();// 获取枚举常量的描述信息 17 } 18 19 /**定义请求成功的：状态码，描述，结果集数据 20 * @param data 传递的响应结果集数据 21 * @return 有成功状态码，描述，结果集数据的标准格式对象 22 */ 23 public static<T> ResponseData<T> success(T data) { 24 // 创建响应标准格式对象 25 ResponseData<T> responseData = new ResponseData<T>(); 26 // 调用转换器方法，将（成功）枚举常量解析，放入到标准响应数据中。 27 responseData.parserEnum(EnumCode.SUCCESS); 28 // 放入响应数据 29 responseData.setData(data); 30 return responseData; 31 } 32 33 34 /*定义请求失败的：状态码，描述，不包含结果集数据 35 * @param enumCode 失败时传递的常见错误枚举常量 36 * @return 有失败状态码，描述，没有结果集数据的标准格式对象 37 / 38 public static<T> ResponseData<T> error(EnumCode enumCode) { 39 // 创建响应标准格式对象 40 ResponseData<T> responseData = new ResponseData<T>(); 41 // 调用转换器方法，将（错误）枚举常量解析。 42 responseData.parserEnum(enumCode); 43 return responseData; 44 } 45 46 / 有成功，有失败，但是失败的状态描述不一定能全部满足需求（枚举类有限），所以，自定义方法实现自定义信息 47 * @param code 自定义的状态码 48 * @param message 自定义的错误信息 49 * @return 有失败自定义状态码，自定义描述，没有结果集数据的标准格式对象 50 */ 51 public static<T> ResponseData<T> generator(int code,String message) { 52 // 创建响应标准格式对象 53 ResponseData<T> responseData = new ResponseData<T>(); 54 responseData.setCode(code); 55 responseData.setMessage(message); 56 return responseData; 57 } 58 59 }

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

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

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

1 1 @Api(value = "测试SwaggerAPI Annotation", tags = "Swagger测试之用户信息管理API")
2 2 @RestController
3 3 @RequestMapping("/user")
4 4 public class SwaggerController {
5 5     
6 6     @ApiIgnore    // 忽略这个API
7 7     @GetMapping("/hello")
8 8     public String hello() {
9 9         return "hello";
1010     }
1111     
1212     @GetMapping(value = "/swaggerGet/{name}")
1313     @ApiOperation(value = "接口方法说明", notes = "接口的详情描述")
1414     @ApiImplicitParam(name = "name", value = "请传递一个用户名参数",required = false,dataType = "String", paramType = "path")
1515     public ResponseData<String> swaggerGet(@PathVariable String name) {
1616         // 调用成功的解析方法，并传递响应数据
1717         ResponseData<String> responseData = ResponseData.success(name);
1818         return responseData;
1919     }
2020     
2121     @PostMapping(value = "/swaggerPost")
2222     @ApiOperation(value = "新增用户", notes = "Swagger测试RESTful之POST请求测试入参一个POJO（JSON格式）")
2323     public ResponseData<User> swaggerGet(@RequestBody User user) {
2424         // 调用成功的解析方法，并传递响应数据
2525         ResponseData<User> responseData = ResponseData.success(user);
2626         return responseData;
2727     }
2828     
2929 }

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

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

SpringBoot整合Swagger与REST接口返回值

测试结果如下：

SpringBoot整合Swagger与REST接口返回值

原文链接： https://www.cnblogs.com/xsge/p/13996625.html

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风格暴露接口