Spring Boot Tutorial
Creating Project
Project Components
Tool Suite
- hello-world-example
- project-deployment-using-tomcat
Spring Boot AOP
Spring Boot Database
Spring Boot View
- sb-thymeleaf-view
SB Caching
Spring Boot Misc
Spring Boot - RESTful
Spring Tutorial
- spring-tutorial
Spring Cloud
- spring-cloud-tutorial
Spring Microservices
- spring-microservices-tutorial
Interview Questions
- spring-interview

Configuring Auto Generation of Swagger Documentation

Swagger

A Swagger is an open-source tool. It builds around the OpenAPI Specification that helps developers to design, build, document, and consume RESTful APIs. It is the most popular API documentation format for RESTful Web Services. It provides both JSON and UI support. JSON can be used as a machine-readable format, and Swagger-UI is for visual display, which is easy for humans to understand by just browsing the API documentation. The main Swagger tools are:

Swagger UI: It creates interactive API documentation.
Swagger Editor: It is a browser-based editor where we can write OpenAPI specifications.
Swagger Codegen: It generates server stubs (API implementation stub), and client libraries form an OpenAPI specification.

An OpenAPI Specification (formerly known as Swagger Specification) is an API documentation format for REST APIs. An Open API file allows us to describe our entire API, including:

Available endpoints (/users) and operations on each endpoint (GET /users, POST /users).
Operation parameters for each operation.
Authentication methods.
Contact information, license, the term of use and other information

Let's generate Swagger documentation for our RESTful services.

Step 1: Open pom.xml and add springfox-swagger2 dependency.

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

    

Add another dependency springfox-swagger-ui

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

    

Now we need to configure Swagger.

Step 2: Create a class with the name SwaggerConfig.java and write the following code.

Docket: A builder that is intended to be the primary interface into the swagger-Spring MVC Framework. Docket provides sensible defaults and convenience methods for configuration.

     package com.w3cschoool.server.main;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import springfox.documentation.spi.DocumentationType;
import springfox.documentation.spring.web.plugins.Docket;
import springfox.documentation.swagger2.annotations.EnableSwagger2;
@Configuration
//Enable Swagger
@EnableSwagger2
public class SwaggerConfig 
{
//creating bean
@Bean
public Docket api()
{
//creating constructor of Docket class that accepts parameter DocumentationType
return new Docket(DocumentationType.SWAGGER_2);
}
}

    

Step 3: Run the application.

Step 4: Open the browser and type the URI http://localhost:8080/v2/api-docs

It shows the complete documentation in JSON format, as shown in the following image. It is not much easy to read and understand. Swagger has provided it to be used in other systems like API management tools that offer functionality like API gateways, API caching, API documentation, etc.