如何为 Swagger 注释 Java List form-urlencoded 参数？答案

【问题标题】：How to annotate a Java List form-urlencoded parameter for Swagger?如何为 Swagger 注释 Java List form-urlencoded 参数？
【发布时间】：2022-01-13 08:38:13
【问题描述】：

我有这个 API 端点，它需要一个 form-urlencoded 数组参数。这是相关的Java sn-p：

@POST
@Consumes(MediaType.APPLICATION_FORM_URLENCODED)
@Produces(MediaType.APPLICATION_JSON)
public Response addItems(@Parameter(description = "Items to add") @FormParam("items") List<Long> items) {
    return service.addItems(items);
}

由于以下错误，我无法从生成的 Swagger UI 到达端点：

RESTEASY003870: Unable to extract parameter from http request: javax.ws.rs.FormParam(&quot;items&quot;) value is &#x27;1%2C2%2C3&#x27;

根据我的阅读，Swagger 提出了这个要求：

curl -X 'POST' \
  'http://localhost:8080/items' \
  -H 'accept: */*' \
  -H 'Content-Type: application/x-www-form-urlencoded' \
  -d 'items=1,2,3'

在我看来，罪魁祸首是 Swagger 如何序列化数组：Swagger 发送此 items=1,2,3 而 RESTEasy 期望此 items=1&items=2&items=3。

我已经阅读了相关的Swagger documentation 并尝试了每种样式/爆炸组合，包括那些看起来对我最有意义的组合（style = ParameterStyle.SIMPLE, explode = TRUE，顺便说一句，这应该是默认行为）但没有运气。

那么，我应该如何注释这个端点以便 Swagger 能够调用它？

【问题讨论】：

标签： java swagger resteasy quarkus x-www-form-urlencoded

【解决方案1】：

我使用https://github.com/quarkusio/quarkus-quickstarts/tree/main/openapi-swaggerui-quickstart 并将您的方法添加到 FruitResource

如果你想使用表单 urlencoded，根据 swagger 文档

application/x-www-form-urlencoded 用于将简单的 ASCII 文本数据作为 key=value 对发送。载荷格式类似于查询参数。

https://swagger.io/docs/specification/describing-request-body/，所以它说使用查询参数，我将你的函数更改为


  @POST
  @Consumes(MediaType.APPLICATION_FORM_URLENCODED)
  @Produces(MediaType.APPLICATION_JSON)
  public Response addItems(
    @Parameter(description = "Items to add") @QueryParam(
      "items"
    ) List<Long> items
  ) {
    return service.addItems(items);
  }

然后打开dev-ui

如您所见，UI 正在防止添加错误的参数，请更正下面的 ui

并且创建的 curl 命令按预期工作。

curl -X 'POST' \
  'http://localhost:8080/fruits?items=1&items=2' \
  -H 'accept: */*' \
  -d ''

如果你想测试代码，那就是here。

【讨论】：