You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
I'm using springdoc-openapi-starter-webmvc-ui:2.5.0 and wanted to test a file upload API using SpringDoc's Swagger UI functionality. However, I encountered an issue with the Swagger UI not displaying correctly.
(and I'm using Spring Boot 3.2.3, but I don't think that has anything to do with this issue.)
After examining the Spring WebMVC demo code, I discovered that specific annotations are necessary for it works. Unfortunately, this crucial information wasn't clearly outlined in the official SpringDoc documentation, making it challenging to resolve the issue.
I suggest improving the SpringDoc documentation to provide thorough guidelines for displaying file upload APIs correctly in Swagger UI:
Clearly define parameters using either @RequestPart or @RequestParam.
Ensure that the produces and consumes attributes of the @PostMapping annotation are properly configured to specify media types.
Below is an example demonstrating both working and non-working scenarios:
@RestController@RequestMapping("/demo")
publicclassDemoController {
privatefinalFakeServicefakeService;
publicDemoController(FakeServicefakeService) {
this.fakeService = fakeService;
}
@PostMapping(value = "/work-well", produces = MediaType.APPLICATION_JSON_VALUE, consumes = MediaType.MULTIPART_FORM_DATA_VALUE)
publicResponseEntity<Void> workWell(@RequestPartMultipartFilefile, @RequestParamStringname) {
// This case works correctlyreturnResponseEntity.created(this.fakeService.uploadImage(file, name)).build();
}
@PostMapping(value = "/bad-1", produces = MediaType.APPLICATION_JSON_VALUE, consumes = MediaType.MULTIPART_FORM_DATA_VALUE)
publicResponseEntity<Void> bad1(MultipartFilefile, Stringname) {
// Swagger UI shows file as "string($binary)"// Sending a request via Swagger UI results in a "Value must be a string" validation error.returnResponseEntity.created(this.fakeService.uploadImage(file, name)).build();
}
@PostMapping(value = "/bad-2")
publicResponseEntity<Void> bad2(@RequestPartMultipartFilefile, @RequestParamStringname) {
// Swagger UI shows file as "application/json" type Request bodyreturnResponseEntity.created(this.fakeService.uploadImage(file, name)).build();
}
@PostMapping(value = "/bad-3")
publicResponseEntity<Void> bad3(MultipartFilefile, Stringname) {
// Same result as bad1returnResponseEntity.created(this.fakeService.uploadImage(file, name)).build();
}
}
I hope this helps in effectively communicating the issue, and I encourage the SpringDoc team to consider enhancing the documentation to address this concern.
The text was updated successfully, but these errors were encountered:
I'm using
springdoc-openapi-starter-webmvc-ui:2.5.0
and wanted to test a file upload API using SpringDoc's Swagger UI functionality. However, I encountered an issue with the Swagger UI not displaying correctly.(and I'm using Spring Boot 3.2.3, but I don't think that has anything to do with this issue.)
After examining the Spring WebMVC demo code, I discovered that specific annotations are necessary for it works. Unfortunately, this crucial information wasn't clearly outlined in the official SpringDoc documentation, making it challenging to resolve the issue.
The official documentation mentions that SpringDoc supports
@RequestPart
andMultipartFile
, but lacks detailed guidance on configuring file upload endpoints.I suggest improving the SpringDoc documentation to provide thorough guidelines for displaying file upload APIs correctly in Swagger UI:
@RequestPart
or@RequestParam
.produces
andconsumes
attributes of the@PostMapping
annotation are properly configured to specify media types.Below is an example demonstrating both working and non-working scenarios:
I hope this helps in effectively communicating the issue, and I encourage the SpringDoc team to consider enhancing the documentation to address this concern.
The text was updated successfully, but these errors were encountered: