我正在为各种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中定义List s和Map s？搜索时，我没有找到任何关于这个主题的内容。
1条答案
按热度按时间zlhcx6iw1#
**TL; DR：**OpenAPI规范中确实支持哈希Map和列表。
好吧，为了详细回答您的问题，让我首先让您了解列表和Map在
OpenAPI中是如何工作的，尽管它们可能看起来并不直接，也没有在文档中通过命名清楚地记录下来，但它们确实存在。列表基本上就是数组，所以
OpenAPI提供了类型为query的参数输入来支持，在声明参数类型的同时，还需要指定参数的data-type，如下所示。如上所示，你需要定义
items部分，在这里你定义了列表中元素的类型，在你的例子中，它是一个字符串列表。所以，如果你为这个定义生成一个客户端代码，你会看到它在api定义中生成了一个字符串列表，如下所示。正如你所看到的，它被生成为
@RequestParam类型的输入值，所以，你现在可能明白列表确实以这种方式存在于OpenAPI定义中。对于Map也是如此，在
OpenAPI文档中它们通常被记录为dictionary，这与JavaHashMap是一样的。在OpenAPI中，我们可以在规范中定义模型时使用additionalProperties属性。例如，您希望请求主体作为Rest API中的HashMap，即要实现这一点，您需要编写OpenAPI规范，如下所示：
现在，让我们验证一下上面创建的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端点生成的代码时，它需要一个"请求"Map来接收请求，如下所示。现在，你可能会想为什么它只是
@RequestBody Request request而不是@RequestBody HashMap<String,Object> request，对吗？但是让我告诉你，它只是一个HashMap而不是一个对象!!***但是怎么做呢？***。为了回答这个问题，我在路径src/main/java/io/swagger/model的生成的源代码文件夹中转到以下位置，并查找名为Request.java的文件（在您的例子中，您的文件名可能会根据您在OpenAPI规范中对Map的命名而有所不同，在我的例子中，我将其命名为Request）。基本上，swagger将OpenAPI规范中定义的所有生成的模型都保存在这个位置。因此，查看www.example.com模型类，Request.java model class , i found this at the class level declaration .所以，到现在为止，您应该已经理解生成的模型类是扩展类型为
HashMap<String,Object>的Map，所以基本上Request是HashMap，因为它扩展了HashMap<String,Object>，这正是您所期望的。我尝试在Request对象上调用一个基于map的方法，它正在工作，因为我的IDE正在为HashMap相关方法提供建议，表明它确实是一个HashMap!!因此，我们可以很容易地推断出HashMaps（又名字典）和Lists（又名数组）在
OpenAPI规范中可用于设计数据模型，这样当您生成它们时，您可以通过深入挖掘文档将它们转换为相应的数据结构。您可以通过以下链接阅读更多关于它们的信息：https://swagger.io/docs/specification/data-models/dictionaries/https://swagger.io/docs/specification/describing-parameters/