Swagger UI、SpringDoc、OpenAPI 3.0：POST 正文而不是 textarea 的 UI 字段？

Question

• SpringDoc 1.5.3（最新）
• SwaggerUI 3.41.0（最新）

Swagger UI 为@RequestParam显示了不错的字段。

我有一个 POST 端点，所以我使用了@RequestBody 。
我可以发送一个 JSON，它会解析到我的身体 object 中。 到目前为止，一切都很好。

但是 Swagger UI 只显示一个文本区域，我应该把整个 JSON 放在那里。 这不太方便。

我希望 Swagger UI 显示请求 class 的每个属性的各个字段； 并在没有 YAML 的情况下拥有它 - 只是带有注释。 虽然，如果没有其他选择，YAML 解决方案是可以的。

我发现最接近的是@ParameterObject对 POST 的支持，这里讨论：

class MyParam (
    val a: String,
    val b: SomeEnum,
    @field:Parameter(required = false)
    val someId: String?,
)

@PostMapping("/...", consumes = [ MediaType.APPLICATION_JSON_VALUE ])
fun addMyEntity(
      @ParameterObject param: MyParam
)

但是，这似乎是从查询参数构建 object。

在 SpringFox 中，曾经有@ApiModel和@ApiModelParameter ，我想它们会这样做。 SpringDoc 迁移页面建议用@Schema替换它，但我不知道怎么做。

有没有什么东西可以让 Swagger UI 以相同的方式显示来自 class 的字段，但从中组装一个 JSON 主体？ Spring 仍然会从正文中解析它吗？

也许是这样的：

fun addInsisPaymentRequest(
      @BodyObject param: MyParam
)

Answer 1

我怀疑您提出的解决方案的可行性。 其原因是， POST/PUT请求接受一个请求正文，正如您所知，它可以采用任何有效的负载。

有效负载的范围可以从原始类型到应用程序使用的自定义对象。 此外，数据类型不限于 JSON，还可以是 XML、HAL 等。

此外，值得注意的一点是任何有效的 Json/Xml 都可以有递归对象。 考虑下面的例子。

{
  "prop1": "val1",       // 1st order element
  "prop2": {             // 1st order element
    "sub-prop1": "val2", // 2nd order element
    "sub-prop2": [       // 2nd order element
      "val3",
      "val4"
    ]
  }

现在出现的问题是，对于所有这些，您可以使用类似于我们对查询参数的表示，但是您将如何表示它们应该出现的顺序？

就@ParameterObject而言，它们大多是原始类型。 尽管将它们作为复杂类型并非不可能，但我认为我们中的很多人并不经常这样做。