How to upload a file in spring boot Java | Upload an image in Spring Boot

File uploading is a common requirement in modern web applications. Whether it's for uploading profile pictures, documents, or other types of media, knowing how to implement file uploads is essential for backend developers. In this guide, we’ll walk you through the end-to-end process of uploading a file in a Spring Boot application, including the necessary configuration, backend logic, and testing.

Table of Contents

1. Prerequisites
2. Project Setup
3. Creating a File Upload API in Spring Boot
4. Handling File Upload in the Controller
5. Saving the Uploaded File
6. Testing the File Upload API
7. Conclusion

1. Prerequisites

Before we dive into file upload implementation, ensure you have the following:

• Java 8 or higher installed.
• Maven or Gradle for dependency management.
• A basic understanding of Spring Boot and REST APIs.

2. Project Setup

First, you need to create a Spring Boot project using Spring Initializr. You can include the following dependencies:

• Spring Web: For building REST APIs.
• Spring Boot DevTools (Optional): For hot-reloading during development.

Maven Dependency Setup

Add the necessary dependencies to your pom.xml:

<dependencies>
    <dependency>
        <groupId>org.springframework.boot</groupId>
        <artifactId>spring-boot-starter-web</artifactId>
    </dependency>
</dependencies>

Alternatively, if you're using Gradle, your build.gradle should include:

dependencies {

    implementation 'org.springframework.boot:spring-boot-starter-web'

}

3. Creating a File Upload API in Spring Boot

Next, create a REST API endpoint that accepts file uploads. This will be handled by a controller in Spring Boot.

Step 1: Enable File Upload Support

Spring Boot provides a built-in file upload mechanism. To enable file upload, add the following properties in your application.properties or application.yml file:

For application.properties:

spring.servlet.multipart.max-file-size=5MB

spring.servlet.multipart.max-request-size=5MB

This sets the maximum file size to 5MB.

Step 2: Create the File Upload Controller

Create a controller that handles file uploads. Below is a sample implementation:

import org.springframework.web.bind.annotation.*;

import org.springframework.web.multipart.MultipartFile;

import org.springframework.http.ResponseEntity;

import java.io.File;

import java.io.IOException;

@RestController

@RequestMapping("/api/v1/upload")

public class FileUploadController {

    @PostMapping

    public ResponseEntity<String> handleFileUpload(@RequestParam("file") MultipartFile file) {

        String uploadDirectory = System.getProperty("user.dir") + "/uploads";        

        // Create the directory if it does not exist

        File dir = new File(uploadDirectory);

        if (!dir.exists()) dir.mkdirs();        

        try {

            // Save the file locally

            file.transferTo(new File(uploadDirectory + "/" + file.getOriginalFilename()));

            return ResponseEntity.ok("File uploaded successfully!");

        } catch (IOException e) {

            return ResponseEntity.status(500).body("File upload failed: " + e.getMessage());

        }

    }

}

 Here’s what’s happening:

• @RestController is used to mark this class as a REST controller.
• The handleFileUpload method is mapped to the /api/v1/upload endpoint.
• The MultipartFile object captures the uploaded file. The transferTo method stores the file in a local directory.

4. Handling File Upload in the Controller

In Spring Boot, the MultipartFile interface represents the uploaded file received from a client. It provides methods like:

• getOriginalFilename(): To get the file’s original name.
• getSize(): To get the size of the uploaded file.
• transferTo(): To transfer the file to a specified location.

For file uploads larger than the allowed size, Spring Boot will automatically return an HTTP 413 Payload Too Large error. This is controlled by the properties you set in application.properties.

5. Saving the Uploaded File

In the controller above, we used the method file.transferTo(new File(destination)) to save the file to a folder called uploads in the project directory.

To customize the file storage, such as saving to a database or cloud storage like AWS S3, you would need to adjust the file storage logic accordingly.

For example, saving the file to the /uploads directory within your project directory:

String uploadDirectory = System.getProperty("user.dir") + "/uploads";

If you’re working in a real-world application, make sure to store the file path in your database so it can be retrieved later.

6. Testing the File Upload API

You can test your file upload functionality using tools like Postman or cURL.

Test with Postman

1. Open Postman and create a new POST request.
2. Use the URL: http://localhost:8080/api/v1/upload
3. In the Body tab, select form-data and use the key file.
4. Choose the file you want to upload and send the request.

Test with cURL

Alternatively, you can use cURL to upload a file:

curl -F 'file=@path_to_file' http://localhost:8080/api/v1/upload

7. Conclusion

In this article, we explored the steps involved in uploading a file in a Spring Boot application. From configuring the project, building a REST API, handling file uploads in the controller, to saving the uploaded file — we covered an end-to-end flow.

This solution can be extended to store files in cloud storage, implement file validation, or handle more complex scenarios like multiple file uploads.

With this knowledge, you're now ready to implement file uploads in your Spring Boot projects.

Keywords: Spring Boot file upload, upload file Spring Boot example, multipart file Spring Boot, Spring Boot file handling, Java file upload, Spring Boot tutorial, REST API file upload.