Java Jersey 中使用 Swagger 将 String 输入转换为 Wrapper 提升清晰度和文档编制

在 Java Jersey 中使用 Swagger：将 String 输入转换为 Wrapper

简介

在使用 Jersey Jax-RS 和 Swagger 集成的 Java EE 项目中，有时需要将 API 端点的字符串输入转换为更详细的结构以提高清晰度和文档编制。本文将指导您完成将字符串输入转换为自定义 Wrapper 类所需的过程。

需求

为了使 SwaggerUI 中的 API 端点更加直观，本文的任务是将模糊的字符串输入转换为更详细的结构，称为 "Wrapper?"。本需求要求不使用注解，而是更改输入的类型/结构。

解决方案

1. 创建 Wrapper 类

创建一个 Wrapper 类，其中包含代表 JSON 字符串字段的属性。例如，可以创建一个 CustomerDataReq 类：

public class CustomerDataReq {
    private String cic;
    private String facility;
    private String macroFacility;
    private String productCode;
}

2. 修改 MyResource

修改 GetCustomerData 方法以接受 CustomerDataReq 作为输入：

@POST
@Path("GetCustomerData")
@Produces(MediaType.APPLICATION_JSON)
@Consumes(MediaType.APPLICATION_JSON)
public GetCustomerDataRes GetCustomerData(CustomerDataReq req) { ... }

3. 配置 Swagger

更新 Swagger 配置中的参数类型：

parameters:
  - name: req
    in: body
    required: true
    schema:
      $ref: '#/definitions/CustomerDataReq'

4. SwaggerUI 中的 JSON 示例

现在，SwaggerUI 中的 JSON 示例可以更清晰地表示输入结构：

{
  "cic": "12345",
  "productKey": {
    "facility": "facility1",
    "macroFacility": "macroFacility1",
    "productCode": "productCode1"
  }
}

优势

使用 Wrapper 类的优点包括：

• 增强 SwaggerUI 中的 API 端点文档清晰度。
• 通过强制使用定义明确的属性来改善输入验证。
• 允许在不影响其他端点的 Swagger 集成中修改输入结构。

常见问题解答

问：这种方法在性能方面有什么影响？

答：由于使用 JavaBeans，因此性能影响微乎其微。

问：是否可以在其他 Jersey 应用程序中重用 Wrapper 类？

答：是的，Wrapper 类可重用，只要在所有应用程序中使用相同的 JavaBeans 规范即可。

问：除了 Wrapper 类之外，还有其他方法可以实现此需求吗？

答：还有其他方法，例如使用 DTO（数据传输对象），但 Wrapper 类是一种简单有效的选择。

结论

通过将字符串输入转换为 Wrapper，我们能够显著提高 API 端点在 SwaggerUI 中的清晰度和文档编制。这种方法不使用注解，并为输入验证和结构修改提供了灵活性。本文为在 Java Jersey 应用程序中集成 Swagger 提供了宝贵的见解和分步指南。