java - springdoc-openapi : How to add example of POST request?

Question

有以下Controller方法:

    @ApiResponses(value = {@ApiResponse(responseCode = "200")})
    @GetMapping(value = API_URI_PREFIX + PRODUCTS_URI, produces = MediaType.APPLICATION_JSON_VALUE)
    @ResponseStatus(HttpStatus.OK)
    public Flux<Product> getProducts(@Valid @NotNull PagingAndSorting pagingAndSorting) {
   }

我需要找到一种如何在 Swagger 中显示的方法 PagingAndSorting 的示例目的。
我正在使用 springdoc-api v1.4.3。

Answer 1

您可以使用@ExampleObject 批注。
请注意，如果您想引用示例现有对象，您还可以在示例中使用 ref @ExampleObject(ref="...")。或者理想情况下，从外部配置文件中获取示例并使用 OpenApiCustomiser 添加它们，就像在此测试中所做的那样:

https://github.com/springdoc/springdoc-openapi/blob/master/springdoc-openapi-webmvc-core/src/test/java/test/org/springdoc/api/app90/SpringDocTestApp.java

这是使用@ExampleObject 的示例代码:

@PostMapping("/test/{id}")
public void testme(@PathVariable("id") String id, @RequestBody(content = @Content(examples = {
        @ExampleObject(
                name = "Person sample",
                summary = "person example",
                value =
                        "{\"email\": test@gmail.Com,"
                                + "\"firstName\": \"josh\","
                                + "\"lastName\": \"spring...\""
                                + "}")
})) PersonDTO personDTO) { }

如果您使用的是 @RequestBody Controller 中的Spring注解需要区分两者，例如使用 @io.swagger.v3.oas.annotations.parameters.RequestBody对于 Swagger 注释。这可以防止下面评论中提到的空参数问题。