Spring Boot REST API Documentation With Swagger

Introduction

In this tutorial, we will be integrating a Spring Boot Application with Swagger API documentation. In this post I will be covering only the basic configuration. Advanced configurations and security configurations are not covered in this post.

Swagger API Documentation

Swagger takes the manual work out of API documentation, with a range of solutions for generating, visualizing, and maintaining API docs. For more details visit: Swagger Website.

Requirements to Run the Application:

Java
Maven
IDE of your choice

I am assuming that you have a Basic Knowledge of Spring Boot and have a Basic Spring Boot Application running in your machine. If not, please check my blog on Basic Spring Boot Application by going to the link: Spring Boot Tutorial

Once you have a Basic Spring Boot Application running in your machine, here are the additional steps required to add Swagger API documentation to it.

Step 1: Swagger related Maven Dependencies to be added in pom.xml.

Here are the Swagger related dependencies:

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

Here is the full pom.xml:

<?xml version="1.0" encoding="UTF-8"?>
<project xmlns="http://maven.apache.org/POM/4.0.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/xsd/maven-4.0.0.xsd">
 <modelVersion>4.0.0</modelVersion>
 <groupId>com.aj.basicspringboot</groupId>
 <artifactId>BasicSpringBoot</artifactId>
 <version>1.0.0</version>
    
    <parent>
  <groupId>org.springframework.boot</groupId>
  <artifactId>spring-boot-starter-parent</artifactId>
  <version>2.0.5.RELEASE</version>
 </parent>

 <properties>
        <jdk.version>1.8</jdk.version>
        <java.version>1.8</java.version>
        <swagger.version>2.9.2</swagger.version>
  <packaging>jar</packaging>
 </properties>

 <dependencies>

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

        <!--Swagger API Documentation related dependencies Start-->
        <dependency>
            <groupId>io.springfox</groupId>
            <artifactId>springfox-swagger2</artifactId>
            <version>${swagger.version}</version>
        </dependency>
        <dependency>
            <groupId>io.springfox</groupId>
            <artifactId>springfox-swagger-ui</artifactId>
            <version>${swagger.version}</version>
        </dependency>
        <!--Swagger API Documentation related dependencies End-->

 </dependencies>

 <build>
  <plugins>
            <plugin>
                <artifactId>maven-compiler-plugin</artifactId>
                <version>3.0</version>
                <configuration>
                    <source>1.8</source>
                    <target>1.8</target>
                </configuration>
            </plugin>
   <plugin>
    <groupId>org.springframework.boot</groupId>
    <artifactId>spring-boot-maven-plugin</artifactId>
   </plugin>
  </plugins>
 </build>
</project>

Step 2: Add Swagger Configuration

Swagger configuration requires a Docket Bean. Swagger is enabled through the @EnableSwagger2 annotation.

select() method of Docket bean returns an instance of ApiSelectorBuilder, which gives us a way to control the endpoints exposed by Swagger.

Predicates for selection of RequestHandlers can be configured with the help of RequestHandlerSelectors and PathSelectors. If any() is used for both then this will make the documentation for all the APIs available in your application through Swagger. I have used a RequestHandlerSelectors.basePackage() method as I have all my APIs in the package: com.aj.basicspringboot.controller.

Here is the code for SwaggerConfiguration.java:

package com.aj.basicspringboot.configuration;

import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import springfox.documentation.builders.PathSelectors;
import springfox.documentation.builders.RequestHandlerSelectors;
import springfox.documentation.spi.DocumentationType;
import springfox.documentation.spring.web.plugins.Docket;
import springfox.documentation.swagger2.annotations.EnableSwagger2;

@Configuration
@EnableSwagger2
public class SwaggerConfiguration {
    @Bean
    public Docket productApi() {
        return new Docket(DocumentationType.SWAGGER_2)
                .select().apis(RequestHandlerSelectors.basePackage("com.aj.basicspringboot.controller"))
                .paths(PathSelectors.any())
                .build();
    }
}

Project Setup:

For Java Setup, please refer to: Java Setup
For Maven Setup, please refer to: Maven Setup
For Git and Project Setup, please refer to: Git and Project Setup

Run Application:

1. To run application in your IDE use:
Program arguments: src/main/resources/application.yml

2. To run JAR from command prompt:
Build jar by using command:
mvn clean install
Run JAR by using command in Project folder location:
java -jar target\BasicSpringBoot-1.0.0.jar src\main\resources\application.yml

Please note: I have set the server port as 4000 in application.yml

Results:

Swagger UI

You can test Swagger API Documentation in your browser by visiting:

http://localhost:4000/your-app-root/swagger-ui.html

Since I do not have a root for my app, for me the URL is:

http://localhost:4000/swagger-ui.html

Also present here are the models used in your project

You can also test your API using this UI

Go to the API to test and click on Try it out

Enter the input parameters for the API and click Execute

Check the API response

Conclusion and GitHub link:

This tutorial gives a basic introduction to Spring Boot REST API Documentation with Swagger. The code used in this post is available on GitHub.
Learn the most popular and trending technologies like Machine Learning, Chatbots, Internet of Things (IoT), Big Data Processing, Elastic Stack, Angular 5, Akka HTTP, Play Framework, Dropwizard, Docker, Netflix Eureka, Netflix Zuul, Spring Cloud, Spring Boot, Flask and RESTful Web Service integration with MongoDB, Kafka, Redis, Aerospike, MySQL DB in simple steps by reading my most popular blog posts at Software Developer Central.
If you like my post, please feel free to share it using the share button just below this paragraph or next to the heading of the post. You can also tweet with #SoftwareDeveloperCentral on Twitter. To get a notification on my latest posts or to keep the conversation going, you can follow me on Twitter or Instagram. Please leave a note below if you have any questions or comments.

Search This Blog

Software Developer Central