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

Question

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

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

我有一个 POST 端点，所以我使用了@RequestBody。
我可以发送一个 JSON，它会解析为我的 body 对象。到目前为止一切顺利。

但 Swagger UI 只显示一个文本区域，我应该将整个 JSON 放在其中。哪个不太方便。

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

我找到的最接近的是@ParameterObject 对POST 的支持，讨论了here：

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
)

但是，这似乎是根据查询参数构建对象。

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

是否有什么东西可以让 Swagger UI 以相同的方式显示类中的字段，但从中组装一个 JSON 主体？ Spring 仍然会从 body 中解析它吗？

可能是这样的：

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"
    ]
  }

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

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