Enhance SpringDoc documentation for file upload API configuration

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 and MultipartFile, 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:

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")
public class DemoController {

 private final FakeService fakeService;

 public DemoController(FakeService fakeService) {
 this.fakeService = fakeService;
 }

 @PostMapping(value = "/work-well", produces = MediaType.APPLICATION_JSON_VALUE, consumes = MediaType.MULTIPART_FORM_DATA_VALUE)
 public ResponseEntity<Void> workWell(@RequestPart MultipartFile file, @RequestParam String name) {
 // This case works correctly
 return ResponseEntity.created(this.fakeService.uploadImage(file, name)).build();
 }

 @PostMapping(value = "/bad-1", produces = MediaType.APPLICATION_JSON_VALUE, consumes = MediaType.MULTIPART_FORM_DATA_VALUE)
 public ResponseEntity<Void> bad1(MultipartFile file, String name) {
 // Swagger UI shows file as "string($binary)"
 // Sending a request via Swagger UI results in a "Value must be a string" validation error.
 return ResponseEntity.created(this.fakeService.uploadImage(file, name)).build();
 }

 @PostMapping(value = "/bad-2")
 public ResponseEntity<Void> bad2(@RequestPart MultipartFile file, @RequestParam String name) {
 // Swagger UI shows file as "application/json" type Request body
 return ResponseEntity.created(this.fakeService.uploadImage(file, name)).build();
 }

 @PostMapping(value = "/bad-3")
 public ResponseEntity<Void> bad3(MultipartFile file, String name) {
 // Same result as bad1
 return ResponseEntity.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.

springdoc / springdoc.github.io

Enhance SpringDoc documentation for file upload API configuration #77