2025年swagger 返回值（swagger example value）

大家好，我是讯享网，很高兴认识大家。

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

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

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

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

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

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

讯享网

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

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

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

讯享网

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

讯享网

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

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

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

讯享网

实体类

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

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

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

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

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

例如：

讯享网

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

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

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

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

讯享网

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

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

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

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

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

测试结果如下：

2025年swagger 返回值（swagger example value）

相关推荐