Springdoc-openapi: @Parameter with the same class overrides description

[debargharoy]

When using @Parameter with the same class, the description from only one of them is retained.

Consider the following piece of code

@RequestMapping(value = "/create", method = RequestMethod.POST)
public User createUser(@Parameter(description = "POJO to create User") @RequestBody User user) {
    return userService.createUser(user);
}

@RequestMapping(value = "/delete", method = RequestMethod.DELETE)
public User deleteUser(@Parameter(description = "POJO to delete user") @RequestBody User user) {
    return userService.deleteUser(user);
}

Below is the output during first execution of the application

Below is the output when the application is re-started

Any suggestions on what might be the reason and how can this be resolved?

[bnasslahsen]

@debargharoy,

First of all, your example is not valid from OpenAPI 3 point of view:

• DELETE operations cannot have a requestBody.

This is said, you are sharing the same object between two HTTP Methods, but you swagger-core library resolves objects as reference. Consequently, you will get by default, only one description of the object.

The straightforward way for your example, is to declaire the description on the RequestBody level:

    @PostMapping("/post")
    public ResponseEntity<String> postExample( @RequestBody(description = "POJO to create User") PersonDTO user) {
     ...
    }

    @DeleteMapping("/get")
    public ResponseEntity<String> getExample(@RequestBody(description = "POJO to delete User") PersonDTO user) {
      ...
    }

But, if you absolutely need different descriptions on the object level:

@PostMapping("/post")
public ResponseEntity<String> postExample(@RequestBody(content = @Content(schema = @Schema(ref = "#/components/schemas/userToCreate"))) PersonDTO user) {
    return ResponseEntity.ok("Successful post");
}

@DeleteMapping("/get")
public ResponseEntity<String> getExample(@RequestBody(content = @Content(schema = @Schema(ref = "#components/schemas/userToDelete"))) PersonDTO user) {
    return null;
}

@Bean
public OpenAPI customOpenAPI() {
    return new OpenAPI().components(new Components()
            .addSchemas("userToCreate", getSchemaWithDifferentDescription(PersonDTO.class, "POJO to create User" ))
            .addSchemas("userToDelete", getSchemaWithDifferentDescription(PersonDTO.class, "POJO to delete User" )));
}

private io.swagger.v3.oas.models.media.Schema getSchemaWithDifferentDescription(Class className, String description){
    ResolvedSchema resolvedSchema = ModelConverters.getInstance()
            .resolveAsResolvedSchema(
                    new AnnotatedType(className).resolveAsRef(false));
    return resolvedSchema.schema.description(description);
}

This has been already answred here:

• https://github.com/springdoc/springdoc-openapi/issues/685

[debargharoy]

The @RequestBody you specified belongs to the io.swagger.v3.oas.annotations.parameters package. And I still need to include the @RequestBody from the Spring Framework, as otherwise, the an empty object is initialized with it's attributes as null.
The code thus looks something like

    public User createUser(@io.swagger.v3.oas.annotations.parameters.RequestBody(description = "Create the User") @RequestBody User user) {
        return userService.createUser(user);
    }

Let me know if I'm doing it wrong, so that I can have one RequestBody that does both the work.

[bnasslahsen]

@debargharoy,

Yes, this is correct to combine both spring and swagger @RequestBody annotations.