HelloKoding

Practical coding guides

Spring Boot Swagger REST API Documentation with SpringFox

In this tutorial, you will learn using Swagger and SpringFox to create REST API Documentation in Spring Boot. Let’s reuse the code base of Mapping JPA/Hibernate Entity and DTO with MapStruct

What you’ll need

  • JDK 8+ or OpenJDK 8+
  • Maven 3+
  • MySQL Server 5+ or Docker CE 18+

Init project structure and Swagger dependencies

Project structure

├── src
│   └── main
│       ├── java
│       │   └── com
│       │       └── hellokoding
│       │           └── springboot
│       │               └── restful
│       │                   ├── product
│       │                   │   ├── Product.java
│       │                   │   ├── ProductAPI.java
│       │                   │   ├── ProductDTO.java
│       │                   │   ├── ProductMapper.java
│       │                   │   ├── ProductRespository.java
│       │                   │   └── ProductService.java
│       │                   └── Application.java
│       └── resources
│           └── application.properties
├── Dockerfile
├── docker-compose.yml
└── pom.xml

Setting up Swagger with SpringFox

Add Swagger and Swagger UI dependency into pom.xml .

<properties>
    <io.springfox.version>2.7.0</io.springfox.version>
</properties>

...

<dependency>
    <groupId>io.springfox</groupId>
    <artifactId>springfox-swagger2</artifactId>
    <version>${io.springfox.version}</version>
</dependency>

<dependency>
    <groupId>io.springfox</groupId>
    <artifactId>springfox-swagger-ui</artifactId>
    <version>${io.springfox.version}</version>
</dependency>

...

Config and Run

Configure Swagger

To use Swagger you have to inject @EnableSwagger2 annotation and declare a Docket bean

@Bean
public Docket swagger() {
    return new Docket(DocumentationType.SWAGGER_2)
        .select()
        .apis(RequestHandlerSelectors.any())
        .paths(PathSelectors.any())
        .build();
}

Application.java

package com.hellokoding.springboot.restful;

import org.springframework.boot.SpringApplication;
import org.springframework.boot.autoconfigure.SpringBootApplication;
import org.springframework.context.annotation.Bean;
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;

@SpringBootApplication
@EnableSwagger2
public class Application {
    @Bean
    public Docket swagger() {
        return new Docket(DocumentationType.SWAGGER_2)
                .select()
                .apis(RequestHandlerSelectors.any())
                .paths(PathSelectors.any())
                .build();
    }

    public static void main(String[] args) {
        SpringApplication.run(Application.class, args);
    }
}

Run with Docker

Prepare Dockerfile for Java/Spring Boot application and docker-compose.yml for MySQL Server

Dockerfile

FROM maven:3.5-jdk-8

docker-compose.yml

version: '3'
services:
  hk-mysql:
    container_name: hk-mysql
    image: mysql/mysql-server:5.7
    environment:
      MYSQL_DATABASE: test
      MYSQL_ROOT_PASSWORD: hellokoding
      MYSQL_ROOT_HOST: '%'
    ports:
    - "3306:3306"
    restart: always

  app:
    build: .
    volumes:
    - .:/app
    - ~/.m2:/root/.m2
    working_dir: /app
    ports:
    - 8080:8080
    command: mvn clean spring-boot:run
    depends_on:
    - hk-mysql

Type the below command at the project root directory, make sure your local Docker is running

docker-compose up

Run with JDK/OpenJDK, Maven and MySQL Server local

Update hk-mysql on application.properties to localhost and type the below command at the project root directory

mvn clean spring-boot:run

Testing tine

Access to http://localhost:8080/swagger-ui.html to see REST API Documentation by Swagger UI

Spring Boot Swagger

Try to make a POST to /api/v1/products to create a new product

Spring Boot Swagger

Try a GET request to /api/v1/products to get product list

Spring Boot Swagger

Source code

https://github.com/hellokoding/hellokoding-courses/tree/master/springboot-examples/restful-api/springboot-swagger

Follow HelloKoding