Creating Documentation for Rest Api
Using Swagger to create meaningful documentation in Spring Boot
In the past, creating documentations used to be a chore most developers. However, we Swagger, we can annotate our classes. The only disadvantage is that we will be mixing Swagger annotations in our classes.
Let’s get started.
In this tutorial, we will use one of our REST tutorials, in which we built a simple REST API with CRUD functionalities. You can get a copy from Github.
Swagger offers lots of annotation for use in the classes however, we these ones below:
- @Api — anotates class as a Swagger resource.
- @ApiModel Provides additional information about Swagger models.
- @ApiModelProperty: Adds and manipulates data of a model property.
- @ApiResponses: Provides a wrapper for defining a list of multiple ApiResponse objects.
- @ApiResponse Annotates a single response of an operation.
- @ApiOperation Annotates an operation or typically an HTTP method against a specific path.
The full list of annotations is available here
Tools /Resources for this guide:
- Maven dependences
- IDE
We need the following dependencies
<dependency>
<groupId>io.springfox</groupId>
<artifactId>springfox-swagger2</artifactId>
<version>2.6.1</version>
<scope>compile</scope>
</dependency><dependency>
<groupId>io.springfox</groupId>
<artifactId>springfox-swagger-ui</artifactId>
<version>2.6.1</version>
<scope>compile</scope>
</dependency>
I left the scope as compile because I want it to be available users after we have compiled it.
The complete Pom.xml file for our project is:
<?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>
<parent>
<groupId>org.springframework.boot</groupId>
<artifactId>spring-boot-starter-parent</artifactId>
<version>2.1.3.RELEASE</version>
<relativePath/> <!-- lookup parent from repository -->
</parent>
<groupId>com.zerotoproduction</groupId>
<artifactId>bucketlist</artifactId>
<version>0.0.1-SNAPSHOT</version>
<name>bucketlist</name>
<description>A bucketlist rest api stored in mysql dband deployed to heroku</description>
<properties>
<java.version>1.8</java.version>
</properties>
<dependencies>
<dependency>
<groupId>org.springframework.boot</groupId>
<artifactId>spring-boot-starter-data-jpa</artifactId>
</dependency>
<dependency>
<groupId>org.springframework.boot</groupId>
<artifactId>spring-boot-starter-web</artifactId>
</dependency>
<dependency>
<groupId>io.springfox</groupId>
<artifactId>springfox-swagger2</artifactId>
<version>2.6.1</version>
<scope>compile</scope>
</dependency>
<dependency>
<groupId>org.springframework</groupId>
<artifactId>spring-webmvc</artifactId>
</dependency>
<dependency>
<groupId>io.springfox</groupId>
<artifactId>springfox-swagger-ui</artifactId>
<version>2.6.1</version>
<scope>compile</scope>
</dependency>
<dependency>
<groupId>mysql</groupId>
<artifactId>mysql-connector-java</artifactId>
<scope>runtime</scope>
</dependency>
<dependency>
<groupId>org.springframework.boot</groupId>
<artifactId>spring-boot-starter-test</artifactId>
<scope>test</scope>
</dependency>
</dependencies>
<build>
<plugins>
<plugin>
<groupId>org.springframework.boot</groupId>
<artifactId>spring-boot-maven-plugin</artifactId>
</plugin>
</plugins>
</build>
</project>Configuring Swagger 2
By customizing Swagger, we are providing information about our Api in a class with the necessary annotation. Springfox group id provides @EnableSwagger2 annotation which indicates that Swagger support should be enabled. We should also annotate the class with the @Configuration annotation. A Docket bean holds the configuration.
You need to do some cleaning up.
First create the following packages: config, controller, model and repository.
Our Swagger config looks like this:
package com.zerotoproduction.bucketlist.config;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import org.springframework.http.ResponseEntity;
import org.springframework.web.servlet.config.annotation.ResourceHandlerRegistry;
import org.springframework.web.servlet.config.annotation.ViewControllerRegistry;
import org.springframework.web.servlet.config.annotation.WebMvcConfigurer;
import springfox.documentation.builders.ApiInfoBuilder;
import springfox.documentation.builders.PathSelectors;
import springfox.documentation.builders.RequestHandlerSelectors;
import springfox.documentation.service.ApiInfo;
import springfox.documentation.spi.DocumentationType;
import springfox.documentation.spring.web.plugins.Docket;
import springfox.documentation.swagger2.annotations.EnableSwagger2;
import java.time.LocalDate;
@EnableSwagger2
@Configuration
public class SwaggerConfig implements WebMvcConfigurer {
public SwaggerConfig() {
super();
}
@Bean
public Docket mainConfig() {
return new Docket(DocumentationType.SWAGGER_2)
.apiInfo(apiInfo())
.select().apis(RequestHandlerSelectors.any())
.apis(RequestHandlerSelectors.basePackage("com.zerotoproduction.bucketlist.controller"))
.paths(PathSelectors.regex("/.*"))
.build()
.directModelSubstitute(LocalDate.class, String.class)
.genericModelSubstitutes(ResponseEntity.class)
;
}
@Override
public void addViewControllers(ViewControllerRegistry registry) {
registry.addRedirectViewController("/api/v2/api-docs", "/v2/api-docs");
registry.addRedirectViewController("/api/swagger-resources/configuration/ui", "/swagger-resources/configuration/ui");
registry.addRedirectViewController("/api/swagger-resources/configuration/security", "/swagger-resources/configuration/security");
registry.addRedirectViewController("/api/swagger-resources", "/swagger-resources");
}
@Override
public void addResourceHandlers(ResourceHandlerRegistry registry) {
registry.addResourceHandler("/api/swagger-ui.html**").addResourceLocations("classpath:/META-INF/resources/swagger-ui.html");
registry.addResourceHandler("/api/webjars/**").addResourceLocations("classpath:/META-INF/resources/webjars/");
}
private ApiInfo apiInfo() {
return new ApiInfoBuilder()
.title("Bucket List Rest API")
.description("This page lists all the rest apis for Bucket List API.")
.version("1.0")
.build();
}
}Here is the screenshot of the generated docs:
Using Swagger docs, you don’t need to use Postman as you can test your api calls from Swagger.
Get the complete code:
