在 Swagger 中记录 @RequestBody 地图

Question

我正在为各种 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 中定义列表和地图？搜索我没有找到关于这个主题的任何内容

Answer 1

TL;DR : OpenAPI 规范确实支持 HashMap 和列表。

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

1. 列表

Lists are nothing but basically arrays . So OpenAPI does provide parameter input of type query to support that . While stating the type of parameter , you also need to specify data-type of the parameter as shown below to make it work .

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

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

2. 地图

For maps as well , they are documented popularly as dictionary in the OpenAPI documentation which is same thing as a Java HashMap . In OpenAPI, we can make use of the additionalProperties attribute while defining a model in the spec . For example , you want a request body as a HashMap in your Rest API , i.e

@RequestBody Map<String, Object> request

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

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

验证:

Now , let's verify that the OpenAPI definition model that we created above, will get translated into a HashMap , when the code is generated . So , lets generate a Spring based Server Code by going to https://editor.swagger.io/ , then after creating your API definition go to Generate Server > spring . It will generate a Spring based API code based on the API definition that you would have created for your use-case . So , if you go to that zip file and look inside src/main/java/io/swagger/api , there will a file named as <YOUR_API_NAME>Api.java (In my case , just to test your scenario, i edited the default Pet API provided by swagger automatically on https://editor.swagger.io/ , so in my case file name was PetApi.java ) . So , when i looked at the generated code for the API endpoint that requires a "request" map to receive the request , it was like below .

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

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

的方法

结论：

So , We can easily deduce that HashMaps (aka dictionaries) and Lists (aka arrays) are available in the OpenAPI spec for designing data-models so that when you generate them you can convert them to corresponding data structures as shown above by digging in the documentation deeper . You can read more about them by going at following links :

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

希望对您有所帮助！！ :)

在 Swagger 中记录 @RequestBody 地图

Document a @RequestBody Map in Swagger

api

rest

swagger

spring-boot

openapi

TL;DR : OpenAPI 规范确实支持 HashMap 和列表。