Search code examples
javaswaggeropenapi

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

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:

desire

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

description was added to Schemas panel Book entity !!! result

What is the problem?

Solution

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