在 Swagger 中记录 @RequestBody 映射

Posted 2023-02-26

【中文标题】在 Swagger 中记录 @RequestBody 映射

【英文标题】：Document a @RequestBody Map in Swagger

【发布时间】：2021-03-16 11:01:39

【问题描述】：

我正在为各种 APi 的文档创建 swagger 文件。在控制器中，我遇到了请求 RequestParam 和 RequestBody 的情况：

@PostMapping("/message-now/save-with-params")
    @Timed(value = MetricsTimerConstants.storeMessageWithParamsTimer)
    public ResponseEntity<Object> saveMessageWithParams(@RequestBody Map<String, Object> request,
            @RequestParam List<String> params)  .....

有没有办法在 OpenApi 中定义列表和地图？搜索我没有找到关于这个主题的任何内容

【参考方案1】：

TL;DR :OpenAPI 规范确实支持 HashMaps 和 Lists。

好吧，为了详细回答您的问题，让我首先让您了解列表和地图在 OpenAPI 中的工作原理，尽管它们可能不会直接向前看，并且通过命名在文档中清楚地记录了这一点，但它们确实存在。

1. 列表

列表基本上就是数组。所以OpenAPI 确实提供 query 类型的参数输入来支持它。在陈述的同时 参数类型，还需要指定data-type 如下所示的参数以使其工作。

如上所示，您需要定义items 部分，在该部分中定义列表中元素的类型，在您的情况下，它是一个字符串列表。因此，如果您为此定义生成客户端代码，您将看到它在 api 定义中生成了一个字符串列表，如下所示。

如您所见，它生成为@RequestParam 类型的输入值。所以，您现在可能明白，列表确实以这种方式存在于OpenAPI 定义中。

2. 地图

对于地图，它们通常被记录为dictionary in OpenAPI 文档与 Java HashMap 相同。 在OpenAPI 中，我们可以使用additionalProperties 属性 在规范中定义模型时。例如，您想要一个请求 body 作为你的 Rest API 中的 HashMap ，即

@RequestBody Map<String, Object> request

要完成这项工作，您将编写如下的 OpenAPI 规范：

注意：上面我们创建的 Request 模型，应该在 API 端点的 ref 部分中用作“body”输入类型参数，如下所示。

验证：

现在，让我们验证我们创建的 OpenAPI 定义模型 上面，将被翻译成 HashMap ，当代码生成时 .所以，让我们生成一个基于 Spring 的服务器代码： https://editor.swagger.io/ ，然后在创建 API 定义之后 去Generate Server > spring。它将生成一个基于 Spring 的 API 代码基于您将为您创建的 API 定义 用例。所以，如果你去那个zip文件看看里面 src/main/java/io/swagger/api ，会有一个文件名为 <YOUR_API_NAME>Api.java（在我的情况下，只是为了测试你的场景，我 自动编辑了 swagger 提供的默认 Pet API https://editor.swagger.io/ ，所以在我的情况下文件名是 PetApi.java ) .所以，当我查看生成的 API 端点代码时， 需要一个“请求”映射来接收请求，如下所示。

现在，您可能会想为什么只是@RequestBody Request request 而不是@RequestBody HashMap<String,Object> request 对吧？但是让我告诉你，它只是一个 HashMap 而不是一个对象！ 但是如何？。为了回答这个问题，我去了生成的源代码文件夹中路径src/main/java/io/swagger/model 中的以下位置，并查找了一个名为Request.java 的文件（在您的情况下，您的文件名可能会根据您在OpenAPI 规范中命名您的地图而有所不同，就我而言，我将其命名为 Request) 。基本上，swagger 将 OpenAPI 规范中定义的所有生成模型保存在此位置。因此，查看 Request.java 模型类，我在类级别声明中发现了这一点。

所以，到目前为止，您应该已经明白生成的模型类正在扩展 HashMap<String,Object> 类型的 Map，所以基本上 Request 是 HashMap，因为它扩展了 HashMap<String,Object>，正是您想要的。只是为了让事情更清楚，请看下图，我尝试在 Request 对象上调用基于地图的方法并且它正在工作，因为我的 IDE 正在为 HashMap 相关方法提供建议，表明它确实是一个 HashMap !!

结论：

所以，我们可以很容易地推断出 HashMaps（又名字典）和 列表（又名数组）在 OpenAPI 规范中提供，用于设计数据模型，以便在生成它们时可以转换 通过挖掘它们到相应的数据结构，如上所示 文档更深入。你可以阅读更多关于它们的信息 以下链接：

https://swagger.io/docs/specification/data-models/dictionaries/ https://swagger.io/docs/specification/describing-parameters/

希望对您有所帮助！ :)