Java Spring Boot OpenApi 3 - How to add description for RequestBody?

Question

I want to have a description for RequestBody in spring boot openapi 3, so I make my code like this:

@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 description is Book to add. My desired UI is like this:

But nothing happens. There is no description in my UI.

description was added to Schemas panel Book entity !!!

What is the problem?

Answer 1

From your Code Snippet, it seems to me as if your description actually belongs into the @RequestBody Annotation instead of the @Schema Annotation.

With @Schema, you define and describe your Models, but what you actually want to do is to describe the parameter in the context of your operation.

Try something along the lines of:

@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));
}