Spring Boot makes developing RESTful services ridiculously easy, and using Swagger makes documenting your RESTful services much easier.

In SOAP based web services, we had a WSDL to work with. This gave API developers a XML based contract, which defined the API. However, with RESTFul web services, there is no WSDL. Thus our API documentation becomes more critical.

Swagger2 in spring boot:

Swagger 2 is an open source project used to describe and document RESTful APIs.

The Swagger2 specification, which is known as OpenAPI specification. Currently, Springfox, that has replaced Swagger-SpringMVC (Swagger 1.2 and older), is popular for Spring Boot applications. Springfox supports both Swagger 1.2 and 2.0.

We will be using Springfox in our project.

To bring it in, we need the following dependency declaration in our Maven POM.

<dependency>
    <groupId>io.springfox</groupId>
    <artifactId>springfox-swagger2</artifactId>
    <version>2.8.0</version>
    <scope>compile</scope>
</dependency>

we also require Swagger UI. The code to include Swagger UI is this.

<dependency>
    <groupId>io.springfox</groupId>
    <artifactId>springfox-swagger-ui</artifactId>
    <version>2.8.0</version>
    <scope>compile</scope>
</dependency>

Configure Swagger2 in application:

import static springfox.documentation.builders.PathSelectors.regex;

import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;

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;

@EnableSwagger2
@Configuration
public class Swagger2Config {


    @Bean
    public Docket productApi() {
        return new Docket(DocumentationType.SWAGGER_2)
                .select()
                .apis(RequestHandlerSelectors.basePackage("com.test.swagger"))
                .paths(regex("/rest.*"))
                .build()
                .apiInfo(metaInfo());
    }

    @SuppressWarnings("deprecation")
    private ApiInfo metaInfo() {
        return new ApiInfo("Swagger2 Java", "Java Springboot  Swagger Example", "1.0", "", "", "", "");
    }
}

we will create a Docket bean in a Spring Boot configuration to configure Swagger 2 for the application. A Springfox Docket instance provides the primary API configuration with sensible defaults and convenience methods for configuration.

Swagger2 annotations for REST endpoints:

At this point, if you click the root-controller link, Swagger-UI will display the documentation of our operation endpoints, like this.

We can use the @Api annotation on our RootController class to describe our API.

@RestController
@RequestMapping("/rest")
@Api(value = "RootController Resource", description = "Welcomes  Users")
public class RootController {

}

For each of our operation endpoint, we can use the @ApiOperation annotation to describe the endpoint and Swagger 2 also allows overriding the default response messages of HTTP methods. You can use the @ApiResponse annotation to document other responses.

    @GetMapping("/welcome")
    @ApiOperation(value = "Welcome  User")
    @ApiResponses(value = {
            @ApiResponse(code = 200, message = "Success")
    })
    public String welcome() {
        return "Welcome";
    }

Swagger2 annotations for Model:

We can use the @ApiModelProperty annotation to describe the properties of the Product model. With @ApiModelProperty, We can also document a property as required.

@Data
public class Address {

    @ApiModelProperty(notes = "Address line 1 of the consignee")
    @NotEmpty(message = "Please provide a Address Line1.")
    private String address_line_1;

    @ApiModelProperty(notes = "Address line 2 of the consignee")
    private String address_line_2;

    @ApiModelProperty(notes = "City of the consignee")
    @NotEmpty(message = "Please provide a City.")
    private String city;

    @ApiModelProperty(notes = "State of the consignee")
    @NotEmpty(message = "Please provide a State.")
    private String state;

    @ApiModelProperty(notes = "Zipcode of the consignee. and it must be 5 digit code")
    @NotEmpty(message = "Please provide a Zipcode.")
    @Size(max = 5)
    private String zip;

    @ApiModelProperty(notes = "Country of the consignee")
    private String country;

}

Swagger2 will generate document like below.