POST Form data with multiple files supporting Swagger 3 Specs

In the first post https://medium.com/@jairam.gauns/post-form-data-with-image-using-spring-rest-template-ae719e30e6fe we saw a simple case where we did a POST request passing in a single file using Springs RestTemplate.

Here we will see a bit more complex but a common scenario as to how we POST multiple files, receive them at an endpoint and also make it working with swagger 3 specs.

This may seem like a simple case, but when we browse the internet we find people usually struggle with multiple file upload with rest template, and even if they succeed to do so, they struggle getting it to work along with swagger 3 API specification.

So today we will see a way to solve this problem.

Problem Statement:

We will choose a use case where the User would upload his selfie along with a list of documents. We will also make sure that the API would work with swagger 3 specifications.

In a microservice architecture, let us say one microservice wants to post the user data, selfie and list of documents to another microservice. To achieve this, we will be using Spring Rest Template and Resource for files.

Caller Service:

Here we post the first name, last name, selfie and a list of documents from the microservice where we POST the data using Spring Rest Template. In the below sample Resource will be holding an object of ByteArrayResource for the file type.

Below is the code snippet:

Receiving Service:

This is the API that would be receiving it. Also the swagger 3 specification would be supported.

For swagger 3 Open API specification we can visit the link https://sourabhparsekar.medium.com/open-api-specification-swagger3-fc9ad3bbacdd which gives a detailed explanation about it and how to set it up.

Below is the code snippet of how the controller would looks:

Why POST data in this manner:

We can see that we are accepting data as multipart, where we accept list of files but along with that we are also accepting a JSON of the User data as a String. Here we have to receive the user details in the String format and cannot make use of the UserModel object directly for details to get mapped, as it would fail to convert because we consume only multipart data.

So with this approach we can easily support more complex/nested UserModel JSON details along with support for multiple files.

Secondly using this approach would also support the swagger 3 notations, which benefits us in many ways like exposing these to the UI developers or even backend developers to easily test/integrate this API from a swagger UI.

There are other ways to receive files and JSON data, for example by making use of ModelAttribute for a datamodel and multipart for file or other way is to have a convertor for the datamodel and multipart for a file. But making it work with swagger 3 is another challenge all together. In this Post we stayed more focused to get things working with swagger 3 and also receive data from the rest template.

Getting the APIs to work with swagger 3 is a common requirement nowadays when developing microservices. Just to note we have used springdoc-openapi-ui version 1.5.1 for the above example.

I hope this article would help people in solving the common file upload problem, with an easy way out. :)