Support @Parameter annotation attached to @RequestPart, for several @RequestParts #674
Description
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@Parametertag is read from all the@Parameterattached 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
