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 desire UI is like this :

But nothings happen ! There is no description in my UI.

description was added to Schemas panel Book entity !!!

What is the problem ?

score 16 · Accepted Answer · answered Nov 02 '20 at 13:25

16

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

answered Nov 02 '20 at 13:25

Gabriel Frassl

176
1
3

@RequestBody does not have description property.it just have required property. – geeekfa Nov 02 '20 at 15:04
Are you using the right Annotation ? https://docs.swagger.io/swagger-core/v2.1.5/apidocs/io/swagger/v3/oas/annotations/parameters/RequestBody.html Maybe you are using the springframework.web... Annotation. Maybe your dependency to swagger-annotations points to an outdated version. – Gabriel Frassl Nov 02 '20 at 15:32
2

yes my friend . thanks alot . we have two RequestBody. 1) io.swagger.v3.oas.annotations.parameters.RequestBody and 2) org.springframework.web.bind.annotation.RequestBody . I should use io.swagger.v3.oas.annotations.parameters.RequestBody – geeekfa Nov 03 '20 at 08:55

score 10 · Answer 2 · answered Nov 03 '20 at 09:05

10

Thanks to Gabriel Frassl.

we should use

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

instead of

org.springframework.web.bind.annotation.RequestBody

so we have good stuffs like description , content , ...

answered Nov 03 '20 at 09:05

geeekfa

1,169
1
10
15

4

But when you use the @RequestBody from swagger the JSON mapping does not work anymore, the properties are just null in the controller, do you have a solution for this? – maxeh May 26 '21 at 09:50
4

Use both of them together: `@io.swagger.v3.oas.annotations.parameters.RequestBody(description = "", required = true, content = @Content(schema = @Schema(implementation = MyClass.class))) @RequestBody MyClass body` – King Midas Mar 28 '22 at 14:58

score 1 · Answer 3 · edited Nov 22 '21 at 07:22

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

For that I add @RequestBody from springframework. It works to me.

Echsecutor · Answer 4 · 2023-04-22T14:21:19.353

To add to the io.swagger.v3.oas.annotations.parameters.RequestBody solution that was pointed out in other answers:

Mind that you do not want to remove the org.springframework.web.bind.annotation RequestBody Annotation when you add the swagger annotation. This might break the endpoint's boddy binding.
You can also add a @Parameter(description = "...") (i.e. io.swagger.v3.oas.annotations.Parameter) to any parameter of your endpoint. This works also for @RequestHeader, @PathVariable,... which might not come with a handy io.swagger.v3.oas.annotations.parameters version like RequestBody.

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

4 Answers4