How to document your REST Services using Springfox Swagger

Springfox Swagger is an useful tool to generate Swagger documentation from the RESTful services code. As you can see from this tutorial, it’s really just a matter of adding one Configuration class to your Spring Boot project ans you are done with it!

You can start from any REST project like our Spring Boot Hello World REST Service .

In order to enable the generation of the documentation automatically, we need to include a @Configuration Bean tagged with @EnableSwagger2:

package com.example.demorest;

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 ConfigSwagger {
  public class SwaggerConfig {
    @Bean
    public Docket api() {
      return new Docket(DocumentationType.SWAGGER_2)
          .select()
          .apis(RequestHandlerSelectors.any())
          .paths(PathSelectors.any())
          .build();
    }
  }
}

In this Bean:

@Configuration : Defines a Spring configuration file

@EnableSwagger2 : The annotation to enable Swagger support

Docket : This is a simple builder class to configure the generation of Swagger documentation using the Swagger Spring MVC framework. By using RequestHandlerSelectors.any()).paths(PathSelectors.any()) : Includes all APIs and paths in the documentation

In order to compile the project, you have to add Swagger2 dependencies:

<?xml version="1.0" encoding="UTF-8"?><project>
   <dependency>
       	
      <groupId>io.springfox</groupId>
       	
      <artifactId>springfox-swagger2</artifactId>
       	
      <version>2.9.2</version>
       
   </dependency>
    
</project>

When we execute the main class, we can launch the API Docs URL ( http://localhost:8080/v2/api-docs ). The following screenshot shows some of the generated documentation. Here is an excerpt of the JSON produced:

{      "swagger": "2.0",     "info": {         "description": "Api Documentation",         "version": "1.0",         "title": "Api Documentation",         "termsOfService": "urn:tos",         "contact": { },         "license": {             "name": "Apache 2.0",             "url": "http://www.apache.org/licenses/LICENSE-2.0"         }     },     "host": "localhost:8080",     "basePath": "/",     "tags": [         {             "name": "customer-controller",             "description": "Customer Controller"         },         {             "name": "basic-error-controller",             "description": "Basic Error Controller"         }     ],     "paths": {         "/": {             "get": {                 "tags": [                     "customer-controller"                 ],                 "summary": "findAll",                 "operationId": "findAllUsingGET",                 "consumes": [                     "application/json"                 ],                 "produces": [                     "*/*"                 ],                 "responses": {                     "200": {                         "description": "OK",                         "schema": {                             "type": "array",                             "items": {                                 "$ref": "#/definitions/Customer"                             }                         }                     },                     "401": {                         "description": "Unauthorized"                     },                     "403": {                         "description": "Forbidden"                     },                     "404": {                         "description": "Not Found"                     }                 }             },             "head": {                 "tags": [                     "customer-controller"                 ],                 "summary": "findAll",                 "operationId": "findAllUsingHEAD",                 "consumes": [                     "application/json"                 ],                 "produces": [                     "*/*"                 ],                 "responses": {                     "200": {                         "description": "OK",                         "schema": {                             "type": "array",                             "items": {                                 "$ref": "#/definitions/Customer"                             }                         }                     },                     "204": {                         "description": "No Content"                     },                     "401": {                         "description": "Unauthorized"                     },                     "403": {                         "description": "Forbidden"                     }                 }             },             "post": {                 "tags": [                     "customer-controller"                 ],                 "summary": "findAll",                 "operationId": "findAllUsingPOST",                 "consumes": [                     "application/json"                 ],                 "produces": [                     "*/*"                 ],                 "responses": {                     "200": {                         "description": "OK",                         "schema": {                             "type": "array",                             "items": {                                 "$ref": "#/definitions/Customer"                             }                         }                     },                     "201": {                         "description": "Created"                     },                     "401": {                         "description": "Unauthorized"                     },                     "403": {                         "description": "Forbidden"                     },                     "404": {                         "description": "Not Found"                     }                 }             },

Great! You have just enriched your REST Services Documentation using Swagger2 in no time.