Spring MVC with Swagger Integration: Deploying Your RESTful API to Heroku

This blog shows you how to create a Spring MVC project with Swagger integration and deploy it to Heroku using Git and Maven.

Table of Contents

1. Introduction

In this tutorial, you will learn how to create a Spring MVC project with Swagger integration and deploy it to Heroku using Git and Maven. This will allow you to build a RESTful API that can be easily documented and tested with Swagger tools. You will also learn how to configure your application for deployment to Heroku, a cloud platform that lets you run your applications with minimal setup and maintenance.

Spring MVC is a popular framework for building web applications with Java. It provides a model-view-controller architecture that simplifies the development of web applications. Swagger is a set of open-source tools for designing, documenting, and testing RESTful APIs. It helps you create interactive and user-friendly documentation for your APIs, as well as generate client and server code from your API specifications. Heroku is a platform as a service (PaaS) that enables you to deploy and run your applications on the cloud. It supports various languages and frameworks, including Java and Spring Boot. Git is a version control system that helps you track and manage changes to your code. Maven is a build automation tool that helps you manage dependencies, compile, test, and package your Java projects.

By the end of this tutorial, you will have a Spring MVC project with Swagger integration that can be deployed to Heroku using Git and Maven. You will also be able to access and test your API using the Swagger UI and documentation. To follow this tutorial, you will need some basic knowledge of Java, Spring Boot, RESTful APIs, and Maven. You will also need to install Java, Spring Tool Suite (STS), Git, and Maven on your local machine.

Are you ready to get started? Let’s begin by setting up your Spring MVC project with Swagger!

2. Setting Up Spring MVC Project with Swagger

The first step of this tutorial is to set up your Spring MVC project with Swagger. This will allow you to create a RESTful API that can be easily documented and tested with Swagger tools. You will use Spring Tool Suite (STS) as your IDE and Maven as your build tool. You will also need to add some dependencies and configuration files to enable Swagger integration.

To set up your Spring MVC project with Swagger, you will need to do the following:

Create a Spring Boot application using STS.
Add Swagger dependencies and configuration to your pom.xml file.
Create a Swagger configuration class to customize your API documentation.
Annotate your controller classes and methods with Swagger annotations.
Test your Swagger UI and documentation using your browser.

Each of these steps will be explained in detail in the following sections. By the end of this section, you will have a Spring MVC project with Swagger integration that can generate interactive and user-friendly documentation for your API.

Are you ready to create your Spring Boot application? Let’s go to the next section!

2.1. Creating a Spring Boot Application

The first step of setting up your Spring MVC project with Swagger is to create a Spring Boot application using Spring Tool Suite (STS). Spring Boot is a framework that simplifies the development and deployment of Spring applications by providing default configurations and dependencies. STS is an IDE that supports the development of Spring applications with various features and tools.

To create a Spring Boot application using STS, you will need to do the following:

Open STS and select File -> New -> Spring Starter Project.
Enter a name for your project, such as spring-swagger-heroku, and choose a location to save it.
Select the packaging type as jar and the Java version as 11.
Click Next and choose the dependencies for your project. You will need to select Spring Web, Spring Data JPA, H2 Database, and Lombok.
Click Finish and wait for STS to create and import your project.

Congratulations! You have created a Spring Boot application using STS. You can now proceed to the next section, where you will add Swagger dependencies and configuration to your project.

2.2. Adding Swagger Dependencies and Configuration

The second step of setting up your Spring MVC project with Swagger is to add Swagger dependencies and configuration to your pom.xml file. This will enable your project to use the Swagger libraries and tools for generating and displaying your API documentation. You will also need to create a Swagger configuration class to customize your API documentation.

To add Swagger dependencies and configuration to your pom.xml file, you will need to do the following:

Add the springfox-boot-starter dependency to your pom.xml file. This dependency will provide the core Swagger libraries and annotations for your project. You can use the latest version available from Maven Repository. For example, you can add the following code snippet to your pom.xml file:

<dependency>
    <groupId>io.springfox</groupId>
    <artifactId>springfox-boot-starter</artifactId>
    <version>3.0.0</version>
</dependency>

Add the springfox-swagger-ui dependency to your pom.xml file. This dependency will provide the Swagger UI, a web-based interface that allows you to view and test your API documentation. You can use the same version as the springfox-boot-starter dependency. For example, you can add the following code snippet to your pom.xml file:

<dependency>
    <groupId>io.springfox</groupId>
    <artifactId>springfox-swagger-ui</artifactId>
    <version>3.0.0</version>
</dependency>

Create a new class in your project named SwaggerConfig and annotate it with @Configuration and @EnableSwagger2 annotations. These annotations will indicate that this class is a configuration class for Swagger and enable the Swagger support for your project. You can create this class in the same package as your main application class or in a separate package for configuration classes. For example, you can create this class in the com.example.spring.swagger.heroku.config package.
In the SwaggerConfig class, create a Bean method named docket that returns a Docket object. This object will provide the configuration for your API documentation, such as the API name, description, version, contact information, license, and base package. You can use the Docket constructor and the apiInfo and select methods to create and configure the Docket object. For example, you can add the following code snippet to your SwaggerConfig class:

@Bean
public Docket docket() {
    return new Docket(DocumentationType.SWAGGER_2)
            .apiInfo(apiInfo())
            .select()
            .apis(RequestHandlerSelectors.basePackage("com.example.spring.swagger.heroku.controller"))
            .build();
}

In the same class, create another Bean method named apiInfo that returns an ApiInfo object. This object will provide the information for your API documentation, such as the API name, description, version, contact information, license, and terms of service. You can use the ApiInfoBuilder class and its methods to create and configure the ApiInfo object. For example, you can add the following code snippet to your SwaggerConfig class:

private ApiInfo apiInfo() {
    return new ApiInfoBuilder()
            .title("Spring MVC with Swagger Integration: Deploying Your RESTful API to Heroku")
            .description("This is a sample RESTful API that demonstrates how to use Spring MVC with Swagger integration and deploy it to Heroku using Git and Maven.")
            .version("1.0.0")
            .contact(new Contact("Your Name", "Your Website", "Your Email"))
            .license("MIT License")
            .licenseUrl("https://opensource.org/licenses/MIT")
            .termsOfServiceUrl("https://www.example.com/terms")
            .build();
}

Congratulations! You have added Swagger dependencies and configuration to your pom.xml file. You can now proceed to the next section, where you will annotate your controller classes and methods with Swagger annotations.

2.3. Testing the Swagger UI and Documentation

The third and final step of setting up your Spring MVC project with Swagger is to test your Swagger UI and documentation using your browser. This will allow you to see how your API documentation looks like and how you can interact with it. You will also be able to test your API endpoints and see the responses and errors.

To test your Swagger UI and documentation using your browser, you will need to do the following:

Run your Spring Boot application using STS. You can right-click on your project and select Run As -> Spring Boot App. This will start your application on the default port 8080.
Open your browser and navigate to http://localhost:8080/swagger-ui/. This will open the Swagger UI, a web-based interface that displays your API documentation. You will see a list of your controller classes and their methods, along with the HTTP methods, paths, parameters, responses, and descriptions.
Click on any of the controller classes or methods to expand them and see more details. You will see a Try it out button that allows you to test your API endpoints. You can enter the values for the parameters and click on the Execute button to see the response and the error codes.
Explore the different features and options of the Swagger UI, such as the Models section that shows the data structures of your API, the Authorize button that allows you to enter the authentication credentials for your API, and the Download button that allows you to download the API specification in JSON or YAML format.

Congratulations! You have tested your Swagger UI and documentation using your browser. You have successfully set up your Spring MVC project with Swagger integration. You can now proceed to the next section, where you will prepare your project for deployment to Heroku.

3. Preparing for Deployment to Heroku

The next section of this tutorial is to prepare your Spring MVC project with Swagger for deployment to Heroku. Heroku is a cloud platform that lets you run your applications with minimal setup and maintenance. You will need to create a Heroku account and app, configure your application properties and Procfile, and add a database service and connection to your project.

To prepare your project for deployment to Heroku, you will need to do the following:

Create a Heroku account and app using the Heroku website or the Heroku CLI.
Configure your application properties file to use the Heroku port and database URL.
Create a Procfile to specify the command to run your application on Heroku.
Add a database service to your Heroku app and connect it to your project.

Each of these steps will be explained in detail in the following sections. By the end of this section, you will have a project that is ready to be deployed to Heroku. You will also be able to access and test your API using the Heroku URL.

Are you ready to create your Heroku account and app? Let’s go to the next section!

3.1. Creating a Heroku Account and App

The first step of preparing your project for deployment to Heroku is to create a Heroku account and app. Heroku is a cloud platform that lets you run your applications with minimal setup and maintenance. You can use the Heroku website or the Heroku CLI to create your account and app.

To create a Heroku account and app using the Heroku website, you will need to do the following:

Go to https://www.heroku.com/ and click on the Sign up button. You will need to enter your email address, name, and password to create your account.
Verify your email address by clicking on the link sent to your email. You will be redirected to the Heroku dashboard, where you can see your apps and resources.
Click on the New button and select Create new app. You will need to enter a name for your app, such as spring-swagger-heroku, and choose a region, such as United States. Then, click on the Create app button.
You will see the app details page, where you can configure your app settings, deploy your code, manage your resources, and monitor your activity.

To create a Heroku account and app using the Heroku CLI, you will need to do the following:

Install the Heroku CLI on your local machine by following the instructions from https://devcenter.heroku.com/articles/heroku-cli.
Open a terminal and run the command heroku login. You will be prompted to enter your email address and password to log in to your Heroku account.
Navigate to the directory where your project is located and run the command heroku create spring-swagger-heroku. This will create a new app with the name spring-swagger-heroku and add a remote repository named heroku to your project.
You will see a message that shows the URL of your app, such as https://spring-swagger-heroku.herokuapp.com/, and the URL of your Git repository, such as https://git.heroku.com/spring-swagger-heroku.git.

Congratulations! You have created a Heroku account and app using the Heroku website or the Heroku CLI. You can now proceed to the next section, where you will configure your application properties and Procfile.

3.2. Configuring the Application Properties and Procfile

The second step of preparing your project for deployment to Heroku is to configure your application properties and Procfile. These files will tell Heroku how to run your application and what port and database to use. You will need to modify your application.properties file and create a Procfile file in your project root directory.

To configure your application properties and Procfile, you will need to do the following:

Open your application.properties file and add the following property:

server.port=${PORT:8080}

This property will tell your application to use the port provided by Heroku or the default port 8080 if none is provided. This will allow your application to run on any port assigned by Heroku.

Create a new file named Procfile in your project root directory and add the following content:

web: java -jar target/spring-swagger-heroku-0.0.1-SNAPSHOT.jar

This file will tell Heroku what command to use to run your application. In this case, you are telling Heroku to run the jar file that is generated by Maven in the target directory. The jar file name may vary depending on your project version, so make sure to use the correct name.

Congratulations! You have configured your application properties and Procfile. You can now proceed to the next section, where you will add a database service and connect it to your project.

3.3. Adding a Database Service and Connecting to It

The third step of preparing your project for deployment to Heroku is to add a database service and connection to your project. You will need to use a database service that is compatible with your project and Heroku, such as PostgreSQL. You will also need to modify your application.properties file and your Entity classes to use the database service and connection.

To add a database service and connection to your project, you will need to do the following:

Go to your Heroku dashboard and select your app. Then, click on the Resources tab and search for Heroku Postgres in the Add-ons section. Click on the Heroku Postgres option and choose a plan, such as Hobby Dev, which is free. Then, click on the Submit Order Form button.
You will see a message that confirms the creation of your database service. You will also see a new configuration variable named DATABASE_URL in your app settings, which contains the connection information for your database service.
Open your application.properties file and add the following property:

spring.datasource.url=${DATABASE_URL}

This property will tell your application to use the database URL provided by Heroku as the data source. This will allow your application to connect to your database service.

Open your Entity classes and add the following annotation above the class declaration:

@Entity
@Table(schema = "public")

This annotation will tell your application to use the public schema of your database service for your entity classes. This will allow your application to map your entity classes to your database tables.

Congratulations! You have added a database service and connection to your project. You can now proceed to the next section, where you will deploy your application to Heroku.

4. Deploying the Application to Heroku

The final section of this tutorial is to deploy your Spring MVC project with Swagger to Heroku. You will use Git and Maven to push your code to the Heroku Git repository and build your application on the cloud. You will also verify the deployment and access your API using the Heroku URL.

To deploy your application to Heroku, you will need to do the following:

Open a terminal and navigate to the directory where your project is located. Run the command git init to initialize a local Git repository for your project.
Run the command git add . to add all the files in your project to the staging area.
Run the command git commit -m "Initial commit" to commit your changes to the local repository.
Run the command heroku login to log in to your Heroku account. You will be prompted to enter your email address and password.
Run the command git remote add heroku https://git.heroku.com/spring-swagger-heroku.git to add the Heroku Git repository as a remote repository for your project. Make sure to use the correct URL for your app.
Run the command git push heroku master to push your code to the Heroku Git repository. This will trigger the Maven build process and deploy your application to Heroku.
You will see a message that shows the status of the deployment and the URL of your app, such as https://spring-swagger-heroku.herokuapp.com/.

Congratulations! You have deployed your application to Heroku. You can now verify the deployment and access your API using the Heroku URL.

To verify the deployment and access your API, you will need to do the following:

Go to your Heroku dashboard and select your app. Then, click on the Open app button to open your app in a new browser tab.
You will see a message that says Whitelabel Error Page. This is because you have not defined a default mapping for the root path of your app. However, this does not mean that your app is not working. You can still access your API endpoints using the Swagger UI and documentation.
Append /swagger-ui.html to the URL of your app, such as https://spring-swagger-heroku.herokuapp.com/swagger-ui.html. You will see the Swagger UI, which shows the details of your API and allows you to test your API operations.
Click on the show/hide button to expand or collapse the API operations. You can also click on the Try it out and Execute buttons to test the API operations and see the responses.
Append /v2/api-docs to the URL of your app, such as https://spring-swagger-heroku.herokuapp.com/v2/api-docs. You will see the Swagger documentation, which shows the JSON representation of your API specifications.

Congratulations! You have verified the deployment and accessed your API using the Heroku URL. You have successfully completed this tutorial and learned how to create a Spring MVC project with Swagger integration and deploy it to Heroku using Git and Maven.

Thank you for reading this tutorial. I hope you found it useful and informative. If you have any questions or feedback, please feel free to leave a comment below. Happy coding!

4.1. Installing Git and Maven

The first step of deploying your Spring MVC project with Swagger to Heroku is to install Git and Maven on your local machine. Git is a version control system that helps you track and manage changes to your code. Maven is a build automation tool that helps you manage dependencies, compile, test, and package your Java projects. You will use Git and Maven to push your code to the Heroku Git repository and build your application on the cloud.

To install Git and Maven on your local machine, you will need to do the following:

Download and install Git from https://git-scm.com/downloads. You will need to choose the appropriate version for your operating system and follow the installation instructions.
Verify that Git is installed by opening a terminal and running the command git --version. You should see a message that shows the version of Git installed, such as git version 2.33.0.
Download and install Maven from https://maven.apache.org/download.cgi. You will need to choose the appropriate version for your operating system and follow the installation instructions.
Verify that Maven is installed by opening a terminal and running the command mvn --version. You should see a message that shows the version of Maven installed, such as Apache Maven 3.8.3.

Congratulations! You have installed Git and Maven on your local machine. You can now proceed to the next section, where you will push your code to the Heroku Git repository.

4.2. Pushing the Code to Heroku Git Repository

The second step of deploying your Spring MVC project with Swagger to Heroku is to push your code to the Heroku Git repository. This will allow you to upload your project files to the cloud and trigger the Maven build process. You will use Git as your version control system and Maven as your build tool.

To push your code to the Heroku Git repository, you will need to do the following:

Open a terminal and navigate to the directory where your project is located. You should have already initialized a local Git repository for your project in the previous section.
Run the command git status to check the status of your local repository. You should see a message that shows the files that are staged, modified, or untracked.
Run the command git add . to add all the files in your project to the staging area. This will prepare them for the next commit.
Run the command git commit -m "Your commit message" to commit your changes to the local repository. You should replace Your commit message with a brief description of the changes you made, such as "Added Swagger dependencies and configuration".
Run the command heroku login to log in to your Heroku account. You should have already created a Heroku account and app in the previous section.
Run the command git remote add heroku https://git.heroku.com/spring-swagger-heroku.git to add the Heroku Git repository as a remote repository for your project. You should use the URL of your app, which you can find in your Heroku dashboard.
Run the command git push heroku master to push your code to the Heroku Git repository. This will upload your project files to the cloud and trigger the Maven build process. You will see a message that shows the status of the deployment and the URL of your app, such as https://spring-swagger-heroku.herokuapp.com/.

Congratulations! You have pushed your code to the Heroku Git repository. You can now proceed to the next section, where you will verify the deployment and access your API using the Heroku URL.

4.3. Verifying the Deployment and Accessing the API

The final step of deploying your Spring MVC project with Swagger to Heroku is to verify the deployment and access your API using the Heroku URL. You will use your browser to open your app and test your API operations using the Swagger UI and documentation. You will also see the JSON representation of your API specifications.