如何仅用Swagger注解实现Swagger UI支持N个动态查询参数

无需编写独立的OpenAPI yaml/json配置文件，仅通过原生Swagger注解即可实现任意数量、自定义键名/键值的查询参数支持，具体配置方式如下：

核心实现逻辑 #

通过注解声明一个query位置的object类型参数，设置表单风格序列化+展开模式，配合后端Map类型参数接收，即可让Swagger UI渲染出支持动态增删键值对的参数输入控件，最终自动拼接成标准的query参数格式发起请求。

代码示例 #

直接在Controller层的接口方法上添加对应注解即可：

import io.swagger.v3.oas.annotations.Operation;
import io.swagger.v3.oas.annotations.Parameter;
import io.swagger.v3.oas.annotations.enums.Explode;
import io.swagger.v3.oas.annotations.enums.ParameterIn;
import io.swagger.v3.oas.annotations.enums.ParameterStyle;
import io.swagger.v3.oas.annotations.media.Content;
import io.swagger.v3.oas.annotations.media.Schema;
import org.springframework.web.bind.annotation.GetMapping;
import org.springframework.web.bind.annotation.RequestMapping;
import org.springframework.web.bind.annotation.RequestParam;
import org.springframework.web.bind.annotation.RestController;
import java.util.Map;

@RestController
@RequestMapping("/swagger")
public class UserController {

    @Operation(summary = "查询用户列表")
    @Parameter(
            in = ParameterIn.QUERY,
            style = ParameterStyle.FORM,
            explode = Explode.TRUE,
            allowReserved = true,
            description = "自定义查询参数，可新增任意数量的键值对",
            content = @Content(schema = @Schema(type = "object", additionalProperties = Schema.STRING_SCHEMA))
    )
    @GetMapping("/users")
    public Object queryUsers(@RequestParam Map<String, String> queryParams) {
        // 所有自定义查询参数会自动封装到queryParams中，直接使用即可
        return queryParams;
    }
}

配置要点 #

• 必须设置style = ParameterStyle.FORM和explode = Explode.TRUE，否则参数无法序列化为key=value&key2=value2的标准query格式
• additionalProperties = Schema.STRING_SCHEMA用于声明该参数支持任意字符串类型的键值对，不要给参数绑定固定的字段结构
• 后端用@RequestParam Map<String, String>接收时，所有URL上携带的查询参数都会被自动解析到Map中，无需额外编写参数解析逻辑
• 配置完成后打开Swagger UI，该接口的参数区域会出现动态添加按钮，点击即可新增自定义参数行，每一行都可以自由输入参数名和参数值，发起请求时会自动拼接为GET swagger/users?name1=value1&name2=value的目标格式。

内容的提问来源于stack exchange，提问作者randomguy