spring-boot - 在 Swagger 中记录 @RequestBody 映射

Question

我正在为各种 API 的文档创建 swagger 文件。在 Controller 中，我请求一个 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 中定义列表和 map ？搜索我在这个主题上一无所获

Answer 1

TL;博士: OpenAPI 规范确实支持 HashMaps 和 Lists。
好吧，要详细回答您的问题，让我首先让您了解 OpenAPI 中列表和 map 的工作原理。 ，虽然他们可能不会直视并通过命名在文档中清楚地记录，但它们确实存在。
1. 列表

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

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

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

For maps as well , they are documented popularly as dictionary inthe OpenAPI documentation which is same thing as a Java HashMap .In OpenAPI, we can make use of the additionalProperties attributewhile defining a model in the spec . For example , you want a requestbody 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 createdabove, will get translated into a HashMap , when the code is generated. So , lets generate a Spring based Server Code by going tohttps://editor.swagger.io/ , then after creating your API definitiongo to Generate Server > spring . It will generate a Spring based APIcode based on the API definition that you would have created for youruse-case . So , if you go to that zip file and look insidesrc/main/java/io/swagger/api , there will a file named as<YOUR_API_NAME>Api.java (In my case , just to test your scenario, iedited the default Pet API provided by swagger automatically onhttps://editor.swagger.io/ , so in my case file name was PetApi.java) . So , when i looked at the generated code for the API endpoint thatrequires 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 规范中命名 map 而有所不同，在我的情况下，我将其命名为请求)。基本上，swagger 将 OpenAPI 规范中定义的所有生成模型都保留在此位置。因此，查看 Request.java 模型类，我在类级别声明中发现了这一点。

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

结论:

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

https://swagger.io/docs/specification/data-models/dictionaries/
https://swagger.io/docs/specification/describing-parameters/
希望有帮助!! :)