Java Spring Boot OpenApi 3 - 如何为 RequestBody 添加描述？

Question

我想在 spring boot openapi 3 中对RequestBody进行描述。 所以我让我的代码是这样的：

@PostMapping(produces = "application/json", consumes = "application/json")
    public ResponseEntity<Book> addBook(
            @Schema(
                    description = "Book to add.",
                    required=true,
                    schema=@Schema(implementation = Book.class))
            @Valid @RequestBody Book book
    ) {
        return ResponseEntity.ok(bookRepository.add(Book));
}

RequestBody描述是Book to add. 我想要的用户界面是这样的：

但什么也没有发生！ 我的用户界面中没有描述。

描述已添加到Schemas面板Book实体！

问题是什么 ？

Answer 1

从您的代码片段来看，在我看来，您的描述实际上属于 @RequestBody 批注而不是 @Schema 批注。

使用@Schema，您可以定义和描述您的模型，但您实际想要做的是在您的操作上下文中描述参数。

尝试一些类似的东西：

@PostMapping(produces = "application/json", consumes = "application/json")
    public ResponseEntity<Book> addBook(
            @RequestBody(description = "Book to add.", required = true,
                        content = @Content(
                                schema=@Schema(implementation = Book.class)))   
            @Valid Book book
    ) {
        return ResponseEntity.ok(bookRepository.add(Book));
}

Answer 2

感谢加布里埃尔·弗拉斯尔。

我们应该使用

io.swagger.v3.oas.annotations.parameters.RequestBody

代替

org.springframework.web.bind.annotation.RequestBody

所以我们有好东西，比如description ， content ，......

Answer 3

@PostMapping(produces = "application/json", consumes = "application/json")
public ResponseEntity<Book> addBook(
        @RequestBody(description = "Book to add.", required = true,
                    content = @Content(
                            schema=@Schema(implementation = Book.class)))   
        @Valid @org.springframework.web.bind.annotation.RequestBody Book book
) {
    return ResponseEntity.ok(bookRepository.add(Book));
}

为此，我从 springframework 添加 @RequestBody。 它对我有用。