Swagger动态参数注解：使用@DynamicParameters实现JSON参数的灵活定义

2023 年 12 月 26 日

255 次浏览

2622字数

在构建RESTful API时，Swagger是一个广泛使用的工具，它可以帮助开发者设计、构建、记录以及使用REST API。Swagger允许通过注解来描述接口的输入输出参数。然而，在某些情况下，API的参数可能不是静态定义的，而是需要动态生成。这时候就可以利用 @DynamicParameters注解来实现JSON参数的灵活定义。

@DynamicParameters注解提供了一种机制来描述那些结构不固定或者随着业务需求变化可能会改变结构的JSON对象。这对于设计灵活性较高或者需要适应快速迭代业务模型API尤为重要。

要使用 @DynamicParameters, 通常需要以下步骤：

引入依赖：确保你已经在项目中引入了Swagger相关依赖，并且配置好了Swagger。
创建动态模型类：创建一个类用于表示动态参数，并且在该类上添加 @ApiModel(value = "YourModelName", description = "Your model description"), 其中 value 和 description 应该根据实际情况填写。
添加属性和方法：在你创建好的模型类中添加属性和方法以满足业务需求，并且对每个属性和方法进行必要说明（如果有必要）。
标记为动态参数：通过将 @JsonRawValue, 和 @JsonProperty("parameters"), 注解加到一个String类型字段上, 使其能够接受任何形式有效JSON字符串作为输入值。
应用到资源端点: 在资源端点（Controller层）, 使用此注释将此类型作为API操作方法中@RequestParam或者 @RequestBody 的一部分。
配置Swagger: 在 Swagger 配置文件中注册自定义模型替换器(ModelSubstitute) 或类型转换器(ModelConverter) 来告诉 Swagger 如何处理这个自定义类型。
生成文档: 启动项目后, Swagger 将根据以上设置自动生成相应文档页面.

例如：

@ApiModel(value = "CustomParams", description = "A set of dynamic parameters")
public class CustomParams {

    @JsonRawValue
    @JsonProperty("parameters")
    private String parameters;

    // Constructor, getters and setters for 'parameters' field
}

@RestController
@RequestMapping("/api")
public class DynamicParameterController {

    @PostMapping("/dynamic-endpoint")
    public ResponseEntity<?> dynamicEndpoint(@RequestBody CustomParams customParams) {
        // Handle the dynamic parameters here.
        return ResponseEntity.ok().build();
    }
}

以上代码展示了如何利用CustomParams 类去接收任意格式 JSON 字符串并作为请求体传递给 /dynamic-endpoint.

总结起来，通过使用SpringFox提供给我们工具箱里面非常有力量但又不太显眼工具———即使面对复杂多变、非标准化数据格式也能轻松驾驭它们———从而大大增强我们系统与外界沟通交流能力同时也保证系统内部数据处理逻辑清晰明确易于维护升级.

请注意，在实际开发过程当中还需要考虑到如何验证传入 JSON 字符串是否有效以及如何处理无效请求等安全性问题。