API component schema description incorrectly overwritten by API parameter description

[marcusportmann]

Describe the bug
The description for a shared API component schema is overwritten by the description for an API parameter.

To Reproduce
Create a class annotated with the @Schema annotation and specify a description. Create a method with a parameter with the type of this class annotated with the @parameter annotation with a description. The description for the shared class is overwritten with description for the parameter.

Organization.java

package digital.inception.party;

import com.fasterxml.jackson.annotation.JsonIgnore;
import com.fasterxml.jackson.annotation.JsonInclude;
import com.fasterxml.jackson.annotation.JsonProperty;
import com.fasterxml.jackson.annotation.JsonPropertyOrder;
import io.swagger.v3.oas.annotations.media.Schema;
import java.util.UUID;

@Schema(
    description =
        "This is the description being overwritten")
@JsonInclude(JsonInclude.Include.NON_NULL)
@JsonPropertyOrder({"id", "name"})
public class Organization {

  @Schema(
      description =
          "The Universally Unique Identifier (UUID) uniquely identifying the organization",
      required = true)
  @JsonProperty(required = true)
  private UUID id;

  @Schema(description = "The name of the organization", required = true)
  @JsonProperty(required = true)
  private String name;

  public Organization() {}

  public UUID getId() {
    return id;
  }

  public String getName() {
    return name;
  }

  public void setId(UUID id) {
    this.id = id;
  }

  public void setName(String name) {
    this.name = name;
  }
}

API Method

  @Operation(summary = "Create the organization", description = "Create the organization")
  @ApiResponses(
      value = {
        @ApiResponse(
            responseCode = "204",
            description = "The organization was created successfully"),
        @ApiResponse(
            responseCode = "400",
            description = "Invalid argument",
            content =
                @Content(
                    mediaType = "application/json",
                    schema = @Schema(implementation = RestControllerError.class))),
        @ApiResponse(
            responseCode = "409",
            description = "An organization with the specified ID already exists",
            content =
                @Content(
                    mediaType = "application/json",
                    schema = @Schema(implementation = RestControllerError.class))),
        @ApiResponse(
            responseCode = "500",
            description =
                "An error has occurred and the request could not be processed at this time",
            content =
                @Content(
                    mediaType = "application/json",
                    schema = @Schema(implementation = RestControllerError.class)))
      })
  @RequestMapping(
      value = "/organizations",
      method = RequestMethod.POST,
      produces = "application/json")
  @ResponseStatus(HttpStatus.NO_CONTENT)
  public void createOrganization(
      @Parameter(name = "organization", description = "This description will overwrite the existing description", required = true)
          @RequestBody
          Organization organization)
      throws InvalidArgumentException, DuplicateOrganizationException, PartyServiceException {

   ...

  }

I believe the problem is in the calculateRequestBodySchema method of the org.springdoc.core.GenericParameterBuilder class.

The code below retrieves the existing component schema and replaces the description with the description for the API parameter.

if (schemaN != null && StringUtils.isEmpty(schemaN.getDescription()) && parameterInfo.getParameterModel() != null) {
			String description = parameterInfo.getParameterModel().getDescription();
			if (schemaN.get$ref() != null && schemaN.get$ref().contains(AnnotationsUtils.COMPONENTS_REF)) {
				String key = schemaN.get$ref().substring(21);
				Schema existingSchema = components.getSchemas().get(key);
				existingSchema.setDescription(description);
			}
			else
				schemaN.setDescription(description);
		}

I am not sure if there is a valid reason for doing this, perhaps if the description doesn't exist for the shared component schema this might be a valid approach. If a description does exist for shared component schema then this behaviour does not seem correct. I am happy to submit a pull request that changes this behaviour to only change the description if it has not already been set for the shared component schema.

I am using springdoc-openapi-common 1.4.6.

[debargharoy]

Not sure, but probably this is a problem with the swagger core library.

The scenario might have been missed as it's uncommon that a schema description is provided. Generally, people go about providing a description at the operation level as that helps to clarify the context in a better way.

[marcusportmann]

As I understand it the schema data structures under #/components/schemas/ are shared and can be reused across multiple operations. If the description provided at an operation level takes preference then it creates a situation where the description provided as part of the last operation "wins".

Imagine operations to create and update that take the same Organization data structure above in the request body, with the corresponding descriptions at an operation level of "The new organization" and the "The existing organization". The second description of "The existing organization", for the update operation, doesn't make sense in the context of the create operation and vice-versa.

I agree that if a description is not specified for the shared data structure then defaulting to the operation description is probably the right thing to do, particularly in the case of data structures that are specific to a particular operation. If one is specified for the shared data structure then overriding it with an operation specific description doesn't seem like the correct approach.

[debargharoy]

Thanks for the PR @marcusportmann. I've also been in the same place a while back.

Until the PR is approved, you can refer the issue #782

[marcusportmann]

Thank you @debargharoy, your comment has been incredibly helpful.

I have replaced all my @parameter annotations with the @io.swagger.v3.oas.annotations.parameters.RequestBody annotation, and specified the description I originally specified on the @parameter annotation on this annotation. As long as this is done consistently the description on the shared schema is no longer overwritten.

It is a pity that both the @org.springframework.web.bind.annotation.RequestBody and @io.swagger.v3.oas.annotations.parameters.RequestBody annotations are required and that the second one needs to be fully qualified but at least my problem has been resolved.

[bnasslahsen]

@marcusportmann,

If you are just having one object in a HTTP POST Method, using @Parameter annotation, is not the most relevant one. You should use instead @RequestBody swagger annotation which was specially designed for this purpose.

The usage of @Parameter annotation in a HTTP POST has more sense, if you have many parameters, and you want for each one a different description. At this moment:

• If the developer fills the @Parameter description, it will be considered as the desired descirption, even the Object referenced by the Parameter annotation has an existing description. This can be useful, in case an object is reused between different HTTP methods, but we want a different description. This is an example, that you can find in the tests:

 	@Operation(summary = "Multiple files and JSON payloads as multi part request")
	@PostMapping(
			value = "multi",
			consumes = MediaType.MULTIPART_FORM_DATA_VALUE,
			produces = MediaType.TEXT_PLAIN_VALUE)
	public String multiFilesInMultiPart(
			@RequestPart("params")
			@Parameter(
					description = "This is the configuration",
					content = @Content(mediaType = MediaType.APPLICATION_JSON_VALUE))
			final JsonRequest jsonRequest,
			@RequestPart(value = "file1", required = false) @Parameter(description = "This is file1")
			final MultipartFile file1,
			@RequestPart(value = "file2", required = false) @Parameter(description = "This is file2")
			final MultipartFile file2) {
		return "Hello World " + jsonRequest.getName();
	}

• If the developer, just wants to reuse the description from the original object that is referenced by the Parameter annotation, he needs not to fill the Parameter description: And this is where a fix can make sense :)