在Swagger中记录@RequestBody映射

html5 • • 问答

我正在为各种 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 中定义列表和地图？搜索我在这个主题上一无所获

回答

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

好吧，要详细回答您的问题，让我首先让您了解列表和映射的工作原理OpenAPI，尽管它们可能不会直视并通过命名在文档中清楚地记录下来，但它们确实存在。

1. 列表

列表只不过是数组。所以OpenAPI确实提供了类型的参数输入query来支持。在说明参数类型的同时，您还需要data-type如下所示指定参数以使其工作。

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

如您所见，它是作为一种@RequestParam输入值生成的。因此，您现在可以理解列表确实OpenAPI以这种方式存在于定义中。

2. 地图

对于地图，它们也被广泛地记录dictionary在OpenAPI文档中，这与 Java 是一样的HashMap。在 中OpenAPI，我们可以additionalProperties在规范中定义模型时使用该属性。例如，您希望在 Rest API 中将请求正文作为 HashMap ，即

@RequestBody Map<String, Object> request

为了完成这项工作，您将编写 OpenAPI 规范，如下所示：

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

验证：

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

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

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

结论：

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

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

希望有帮助！！:)

以上是在Swagger中记录@RequestBody映射的全部内容。
THE END
分享
二维码
< <上一篇
下一篇>>