Swagger UI integration with Spring Boot application

OpenAPI Overview

OpenAPI Specification (formerly Swagger Specification) is an API description format for REST APIs. An OpenAPI file allows you to describe your entire API, including.

· Available endpoints (ex: /users) and operations on each endpoint (GET /users, POST /users)

· Input and output parameters for each operation

· Methods for authentication

· General information like contact info, license, terms of use and other information.

API specifications can be written in YAML or JSON

Swagger Overview

Swagger is a set of open-source tools built around the OpenAPI Specification that can help us design, build, document and consume REST APIs. The major Swagger tools include:

· Swagger Editor — browser-based editor where you can write OpenAPI specs.

· Swagger UI — renders OpenAPI specs as interactive API documentation.

· Swagger Codegen — generates server stubs and client libraries from an OpenAPI spec

Swagger UI Overview

Swagger UI is one of the most popular tools for generating interactive documentation from your OpenAPI document. Swagger UI generates an interactive API console for users to quickly learn about our API and experiment with requests

Integrating Swagger with Spring Boot Apps

Adding maven dependencies

As you can see, here we have used springfox implementation of swagger specification. Visit maven central to check out the latest version.

Springfox-swagger2 dependency allows us to generate swagger api-docs in JSON format whereas springfox-swagger-ui allow us to easily interact with swagger-generated API docs.

Creating Docket Bean

The configuration of swagger mainly centers around the Docket Bean. For our application, we will create a Docket bean in a Spring Boot configuration to configure Swagger 2 for the application.

Springfox Docket bean provides us the primary API configurations. It has the sensible defaults and configuration methods. We will create a new class called SwaggerConfig under /package/config/ to configure the Docket bean which would look like this:

In this configuration class, the @EnableSwagger2 annotation has been used to enable Swagger support. The select() method which has been called on the Docket bean instance would return an ApiSelectorBuilder, which provides the apis() and paths() methods that are used to filter the controllers and methods that are being documented using String predicates.

Here RequestHandlerSelectors.basePackage matches the base package for controllers to filter the API. The regex parameter is optional and has been passed to paths() acts as an additional filter to generate documentation only for the path starting with given path regex.

In the SwaggerConfig class, we have added a metaData() method that returns an ApiInfo object initialized with information about our API.

Swagger API docs

After adding above configuration, if we boot our spring application, we will be able to test the configuration by visiting api-docs API on browser:

http://localhost:8080/v2/api-docs

Here you can see, we have all the information about our REST APIs in the application, but the main issue is readability and ease of understanding.

Swagger UI to rescue

To resolve the readability issue, we want something more intuitive and easier to understand. The Swagger UI does the job for us. We don’t need to write any code to do that since we have already added the required dependency.

Swagger UI can be accessed on following URL:

http://localhost:8080/swagger-ui.html

Customizing Swagger UI

Swagger UI is completely customizable. We have only seen the out of the box UI as of now. Let us see how we can customize the UI based on our needs,

Controller annotations

@Api annotation on our Controller class to describe our API.

For each of our operation endpoints, we can use the @ApiOperation annotation to describe the endpoint and its response type and @ApiResponse annotation to document other responses, in addition to the regular HTTP 200 OK:

Model Annotations

@ApiModelProperty annotation can be used to describe the properties of the Product model. With @ApiModelProperty, we can also document a property as we want.