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

Question

我想在 spring boot openapi 3 中为 RequestBody 提供

description

。 所以我这样写我的代码：

@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.

我想要的用户界面是这样的：

但是什么也没有发生！我的用户界面中没有description

description被添加到

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

感谢 Gabriel Frassl。

我们应该使用

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。它对我有用。

Answer 4

添加到其他答案中指出的

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

解决方案：

• 请注意，在添加 swagger 注释时，您不想删除

  org.springframework.web.bind.annotation

  RequestBody 注释。这可能会破坏端点的 body 绑定。

• 您还可以将

  @Parameter(description = "...")

  （即

  io.swagger.v3.oas.annotations.Parameter

  ）添加到端点的any参数。这也适用于

  @RequestHeader

  ，

  @PathVariable

  ，...可能没有方便的

  io.swagger.v3.oas.annotations.parameters

  版本，如

  RequestBody

  .