SpringBoot:整合Swagger3.0与RESTful接口整合返回值(2020最新最易懂)

Stella981 等级 1208 0 0

一,整合Swagger3.0

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

存在的问题:(面对多个开发人员或多个开发团队)

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

概述

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。

 <!-- SpringBoot整合springfox-swagger3 -->
<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

SpringBoot:整合Swagger3.0与RESTful接口整合返回值(2020最新最易懂)

2,自定义SwaggerConfig类

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

 1 @EnableOpenApi   // 开启Swagger自定义接口文档
 2 @Configuration   // 相当于Spring配置中的<beans>
 3 public class SwaggerConfig {
 4     @Bean   // 相当于Spring 配置中的<bean>
 5     public Docket createRestApi() {
 6         return new Docket(DocumentationType.OAS_30)
 7                 .apiInfo(apiInfo())
 8                 .select()
 9                 .apis(RequestHandlerSelectors.withMethodAnnotation(ApiOperation.class))
10                 .paths(PathSelectors.any())
11                 .build();
12     }
13     // API基础信息定义(就是更新Swagger默认页面上的信息)
14     private ApiInfo apiInfo() {
15         return new ApiInfoBuilder()
16                 .title("Swagger3接口文档测试")
17                 .description("文档描述:更多问题,请联系开发者")
18                 .contact(new Contact("xsge123(name)", "作者网站(url)", "1511868921@qq.com(email)"))
19                 .version("1.0")
20                 .build();
21     }
22     
23 }

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方法。

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

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

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

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

SpringBoot:整合Swagger3.0与RESTful接口整合返回值(2020最新最易懂)

二,统一接口返回值

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

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

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

例如:

1 {
2     "code": 0,
3     "messages": "",
4     "data": ""
5 }

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

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

 1 public enum EnumCode {
 2     // 定义成功的枚举常量,状态码,和描述
 3     SUCCESS(0,"ok"),// 这里的代码相当于:public static  final DataEnumCode SUCCESS = new DataEnumCode(0,“ok”)调用类有参构造传值
 4     // 定义系统异常的枚举常量,状态码,和描述
 5     SYSTEM_ERROR(5001,"服务器系统异常,请稍后..."),
 6     // 定义参数异常的枚举常量,状态码,和描述
 7     PARAMETER_ERROR(5002,"参数异常,认证失败..."),
 8     // 定义用户名存在异常的枚举常量,状态码,和描述
 9     USER_HAS_ERROR(5003,"用户名已存在....");// 注意上面的是逗号分隔,这里结束是分号
10     
11     // 定义的枚举常量属性。
12     private int code;// 状态码
13     private String message;// 描述
14     
15     /**
16      * 私有构造,防止被外部调用
17      */
18     private EnumCode(int code, String message) {
19         this.code = code;
20         this.message = message;
21     }
22      /**
23      * 定义方法,返回描述,跟常规类的定义get没区别
24      * @return
25      */
26     public int getCode() {
27         return code;
28     }
29     public String getMessage() {
30         return message;
31     }
32 }

2.定义Response的标准格式POJO

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

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

  1. 成功方法。请求成功,响应结果集数据,响应状态码,描述,状态码和描述从枚举常量中解析。

  2. 失败方法。请求失败,无结果集数据,响应状态码,描述保留,状态码和描述从枚举常量中解析。(枚举类型有限,不一定满足所有异常)

  3. _失败方法。请求失败,无结果集数据,响应状态码,描述保留,该方法用于解决因为枚举常量的局限性,不足以满足所有需求的问题,实现允许自定义状态码和描述_。

  4. 提供便于解析枚举常量的方法。

    1 @Data 2 @NoArgsConstructor 3 @AllArgsConstructor 4 public class ResponseData { 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 ResponseData success(T data) { 24 // 创建响应标准格式对象 25 ResponseData responseData = new ResponseData(); 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 ResponseData error(EnumCode enumCode) { 39 // 创建响应标准格式对象 40 ResponseData responseData = new ResponseData(); 41 // 调用转换器方法,将(错误)枚举常量解析。 42 responseData.parserEnum(enumCode); 43 return responseData; 44 } 45 46 / 有成功,有失败,但是失败的状态描述不一定能全部满足需求(枚举类有限),所以,自定义方法实现自定义信息 47 * @param code 自定义的状态码 48 * @param message 自定义的错误信息 49 * @return 有失败自定义状态码,自定义描述,没有结果集数据的标准格式对象 50 */ 51 public static ResponseData generator(int code,String message) { 52 // 创建响应标准格式对象 53 ResponseData responseData = new ResponseData(); 54 responseData.setCode(code); 55 responseData.setMessage(message); 56 return responseData; 57 } 58 59 }

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

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

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

 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 = false,dataType = "String", paramType = "path")
15     public ResponseData<String> swaggerGet(@PathVariable String name) {
16         // 调用成功的解析方法,并传递响应数据
17         ResponseData<String> responseData = ResponseData.success(name);
18         return responseData;
19     }
20     
21     @PostMapping(value = "/swaggerPost")
22     @ApiOperation(value = "新增用户", notes = "Swagger测试RESTful之POST请求测试入参一个POJO(JSON格式)")
23     public ResponseData<User> swaggerGet(@RequestBody User user) {
24         // 调用成功的解析方法,并传递响应数据
25         ResponseData<User> responseData = ResponseData.success(user);
26         return responseData;
27     }
28     
29 }

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

Postman测试访问:(输入接口URL,传递参数测试即可)

SpringBoot:整合Swagger3.0与RESTful接口整合返回值(2020最新最易懂)

测试结果如下:

SpringBoot:整合Swagger3.0与RESTful接口整合返回值(2020最新最易懂)

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

收藏
评论区

相关推荐

美团java研发岗二面:覆盖所有面试知识点
面试真题以及解析 Web,RESTful API 在微服务中的作用是什么?微服务架构基于一个概念,其中所有服务应该能够彼此交互以构建业务功能。因此,要实现这一点,每个微服务必须具有接口。这使得 Web API 成为微服务的一个非常重要的推动者。RESTful API 基于 Web 的开放网络原则,为构建微服务架构的各个组件之间的接口提供了最合理的模型。
Spring Boot 无侵入式 实现RESTful API接口统一JSON格式返回
前言现在我们做项目基本上中大型项目都是选择前后端分离,前后端分离已经成了一个趋势了,所以总这样·我们就要和前端约定统一的api 接口返回json 格式,这样我们需要封装一个统一通用全局 模版api返回格式,下次再写项目时候直接拿来用就可以了 约定JSON格式一般我们和前端约定json格式是这样的json "code": 200, "message
个人博客开发之技术选型规划
项目技术1. SpringBoot2.4.7 技术栈2. MybatisPlus3.4.x ORM框架3. Mysql8.0 数据库4. IDEA 2021 开发工具5. Mac pro 电脑6. Redis 缓存7. Thymeleaf 模版引擎 项目架构1. 打算用现在最流行的架构模式,前后端分离,采用RESTful API 规范风格json api
轻松上手SpringBoot+SpringSecurity+JWT实RESTfulAPI权限控制实战
前言我们知道在项目开发中,后台开发权限认证是非常重要的,springboot 中常用熟悉的权限认证框架有,shiro,还有就是springboot 全家桶的 security当然他们各有各的好处,但是我比较喜欢springboot自带的权限认证框架xml org.springframework.boot spr
Go 语言编程 — go
目录 == ### 文章目录 * 目录 * 一个 RESTful API 框架需要什么? * go-restful * 核心概念 * Route * WebService * Container * 过滤器(Filter) * 响应编码(Response Encoding) * 代码示例一 * 代码示例
RESTClient 用法
[**Wisdom RESTClient**](https://www.oschina.net/action/GoToLink?url=https%3A%2F%2Fgithub.com%2Fwisdom-projects%2Frest-client) 一款自动化测试REST API的工具,它可以自动化测试RESTful API并生成精美的测试报告,同时基于测
RESTful API 设计实践
RESTful API 为网络应用程序设计提供了一套统一、合理的风格。它只是一种风格,而不是标准,所以也就没有一套统一的标准去规范化这些设计,本文从实践的角度出发,讨论 RESTful API 设计上的一些细节,探讨如何设计出一套好用、合理、精炼的 API。 版本 -- 按照 RESTful API 的风格,不同版本的 API 应该是同一种资源的不同表现
RESTful API 设计最佳实践
Web API 近几年变得越来越火,而简洁的 API 设计在多后端系统交互应用中也变得尤为重要。通常,会使用 RESTful API 来作为我们的 Web API 。本文介绍了几种简洁 RESTful API 设计的最佳实践。 **使用的名词而不是动词** 使用名词来定义接口 ![](https://static.oschina.net/uploads
RestFul 与 RPC
原文地址:https://blog.csdn.net/u014590757/article/details/80233901 RPC、REST API深入理解 一:RPC RPC 即远程过程调用(Remote Procedure Call Protocol,简称RPC),像调用本地服务(方法)一样调用服务器的服务(方法)。通常的实现有
Shiro 放行Swagger
一、前言 ==== 在使用SpringBoot+Shiro+Mybatis+Swagger开发后台权限管理系统的时候,由于SpringBoot采用了Shiro框架,同时API接口文档使用的Swagger,遇到一个问题,在SpringBoot 集成Shiro后,访问Swagger接口需要登陆才可以,由于在项目成型之前需要做接口测试,所以这里记录下如何在Shi
Spring Boot validator参数验证restful自定义错误码响应
关于spring web应用中关于如何使用 Bean _Validation_ _API_和hibernate-validator的文章已经很多,本文就不再重复叙述,今天要介绍的重点是在SpringBoot restful服务中如何根据不同验证错误响应不同的自定义错误码。下面直接上代码。 一、定义restful统一结果返回 ================
Spring Boot 之 RESRful API 权限控制
摘要: 原创出处:[www.bysocket.com](https://www.oschina.net/action/GoToLink?url=http%3A%2F%2Fwww.bysocket.com) 泥瓦匠BYSocket 希望转载,保留摘要,谢谢! “简单,踏实~ 读书写字放屁” 一、为何用RESTful API ================
SpringBoot:整合Swagger3.0与RESTful接口整合返回值(2020最新最易懂)
**一,整合Swagger3.0** ================== 随着Spring Boot、Spring Cloud等微服务的流行,在微服务的设计下,小公司微服务工程jar小的几十个,大公司大的工程拆分jar多则几百上万个,这么多的微服务必定产生了大量的接口调用。而接口的调用就必定要写接口文档(由开发人员编写)。 存在的问题:(面对多个开发人
Swagger文档化restful接口
1、注解 @Api:用在类上,说明该类的作用。 @ApiOperation:注解来给API增加方法说明。 @ApiImplicitParams : 用在方法上包含一组参数说明。 @ApiImplicitParam:用来注解来给方法入参增加说明。 @ApiResponses:用于表示一组响应 @ApiResponse:用在@ApiResponses
swagger生成接口文档和map类型参数解析
一:swagger是什么? ------------- 1、是一款让你更好的书写API文档的规范且完整框架。 2、提供描述、生产、消费和可视化RESTful Web Service。 3、是由庞大工具集合支撑的形式化规范。这个集合涵盖了从终端用户接口、底层代码库到商业API管理的方方面面。 方法一:使用第三方依赖(最简单的方法) --------