Support @Parameter annotation attached to @RequestPart, for several @RequestParts

[ajeans]

Is your feature request related to a problem? Please describe.
Using a Rest Controller from spring-boot, I want to annotate the parameter names and descriptions of several multi-part parts in a request

• A clear and concise description of what the problem is. Ex. I'm always frustrated when [...]
  As far as I can see, only one @Parameter tag is read from all the @Parameter attached to the request parts

A reproducer is:

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

This is valid spring boot, deploys properly and can be queried with

curl -X POST "http://localhost:8080/multi" -H  "accept: text/plain" -H  "Content-Type: multipart/form-data" -F 'params={"name": "Bob"}'
Hello world Bob

• What is the actual result using OpenAPI Description (yml or json)?

curl http://localhost:8080/v3/api-docs | jq '.paths | {"/multi"}'

The corresponding yml shows that only one @Parameter description was processed,

{
  "/multi": {
    "post": {
      "tags": [
        "foo-controller"
      ],
      "summary": "Multiple files and JSON payloads as multi part request",
      "operationId": "multiFilesInMultiPart",
      "requestBody": {
        "description": "This is file2",
        "content": {
          "multipart/form-data": {
            "schema": {
              "type": "object",
              "properties": {
                "params": {
                  "$ref": "#/components/schemas/JsonRequest"
                },
                "file1": {
                  "type": "string",
                  "format": "binary"
                },
                "file2": {
                  "type": "string",
                  "format": "binary"
                }
              }
            }
          }
        }
      },
      "responses": {
        "400": {
          "description": "Invalid request from client",
          "content": {
            "*/*": {
              "schema": {
                "$ref": "#/components/schemas/ErrorDto"
              }
            }
          }
        },
        "404": {
          "description": "No Handler for request",
          "content": {
            "*/*": {
              "schema": {
                "$ref": "#/components/schemas/ErrorDto"
              }
            }
          }
        },
        "500": {
          "description": "Generic server error",
          "content": {
            "*/*": {
              "schema": {
                "$ref": "#/components/schemas/ErrorDto"
              }
            }
          }
        },
        "415": {
          "description": "Unsupported response media type",
          "content": {
            "*/*": {
              "schema": {
                "$ref": "#/components/schemas/ErrorDto"
              }
            }
          }
        },
        "200": {
          "description": "OK",
          "content": {
            "text/plain": {
              "schema": {
                "type": "string"
              }
            }
          }
        }
      }
    }
  }
}

Describe the solution you'd like

• A clear and concise description of what you want to happen.

I would like each part: params, file1, file2 to get assigned the description corresponding to what was declared in the @Parameter tag.

• What is the expected result using OpenAPI Description (yml or json)?

Not sure, I assume a something like the following, but cannot say whether this is valid according to the spec.

          "multipart/form-data": {
            "schema": {
              "type": "object",
              "properties": {
                "params": {
                  "$ref": "#/components/schemas/JsonRequest",
                  "description": "This is the configuration"
                },
                "file1": {
                  "type": "string",
                  "format": "binary",
                  "description": "This is file1"
                },
                "file2": {
                  "type": "string",
                  "format": "binary",
                  "description": "This is file2"
                }
              }
            }
          }

Describe alternatives you've considered

• A clear and concise description of any alternative solutions or features you've considered.

I tried to add the description of @RequestPart in a @Parameter attached directly (as described), I also tried to attach it through @Operation:parameters with no luck.

Additional context

• Add any other context or screenshots about the feature request here.

The swagger ui is as follows for the reference endpoint

[ajeans]

Thanks a lot @bnasslahsen , this seems to work well and swagger-ui is now looking good. 👍

[ajeans]

Hello The linked commit has an integration test added, see springdoc-openapi-webmvc-core/src/test/java/test/org/springdoc/api/app119/HelloController.java and other files in this folder. Best regards. Le dim. 31 oct. 2021 à 02:28, GoncaloAC ***@***.***> a écrit :

…

How did you eventually achieve your goal? I'm having the same issue and have no clue what to do and the response here doesn't show — You are receiving this because you authored the thread. Reply to this email directly, view it on GitHub <#674 (comment)>, or unsubscribe <https://github.com/notifications/unsubscribe-auth/AASEFQEAMOCWL3HUTBV3BLLUJSES3ANCNFSM4NBUOZKQ> . Triage notifications on the go with GitHub Mobile for iOS <https://apps.apple.com/app/apple-store/id1477376905?ct=notification-email&mt=8&pt=524675> or Android <https://play.google.com/store/apps/details?id=com.github.android&referrer=utm_campaign%3Dnotification-email%26utm_medium%3Demail%26utm_source%3Dgithub>.