Spring Boot and Swagger UI REST API Documentation Tool

Spring Boot Jun 27, 2021

This post briefly documents the usage of Swagger UI, a visual documentation tool making it easy for back end implementation and client side consumption.

Introduction

Swagger UI allows anyone — be it your development team or your end consumers — to visualize and interact with the API’s resources without having any of the implementation logic in place. It’s automatically generated from your OpenAPI (formerly known as Swagger) Specification, with the visual documentation making it easy for back end implementation and client side consumption.

Minimum Software Requirements

Java
SwaggerDoc Open API UI Java Library
Swagger Annotations Java Library

Sample Project

Spring Boot Minimal Web App is the sample Spring Boot web application i've used to illustrate the usage of the aforementioned tool.

Navigate to http://localhost:8080/ to discover the application URLs.

Noticed an issue with this Sample Project? Open an issue or a PR on GitHub!

Dependencies

This implementation has two dependencies, springdoc-openapi-ui and swagger-annotations. The maven/gradle dependencies of the same are mentioned below.

SwaggerDoc Open API UI

<!-- https://mvnrepository.com/artifact/org.springdoc/springdoc-openapi-ui -->
<dependency>
    <groupId>org.springdoc</groupId>
    <artifactId>springdoc-openapi-ui</artifactId>
    <version>1.5.9</version>
</dependency>

// https://mvnrepository.com/artifact/org.springdoc/springdoc-openapi-ui
implementation group: 'org.springdoc', name: 'springdoc-openapi-ui', version: '1.5.9'

Swagger Annotations

<!-- https://mvnrepository.com/artifact/io.swagger/swagger-annotations -->
<dependency>
    <groupId>io.swagger</groupId>
    <artifactId>swagger-annotations</artifactId>
    <version>1.6.1</version>
</dependency>

// https://mvnrepository.com/artifact/io.swagger/swagger-annotations
implementation group: 'io.swagger', name: 'swagger-annotations', version: '1.6.1'

Properties

In the application.properties file configure the following optional key-values.

# https://springdoc.org/properties.html

# For custom path of the swagger-ui HTML documentation
# http://localhost:8080/spring-boot-minimal-webapp.html
springdoc.swagger-ui.path=/spring-boot-minimal-webapp.html

# To enable/disable the swagger-ui endpoint
springdoc.swagger-ui.enabled=true

Basic Usage

Swagger provides with annotations specific to class types (Controller, Model etc.,) which are to be placed and populated with appropriate values.

Model Class Annotations

@ApiModel(description="Simple JavaBean domain object representing RESTcontrollerResponse")
This annotation essentially describes what exactly a model is.

@Schema(description="RESTcontrollerResponse content", example="HTTP Method Handled.", required=true)
Each attribute of the model captures a specific feature. We can describe, provide and examplr and indicate if the attribute is mandatory when initializing the object.

Controller Class Annotations

@Operation(summary="HTTP GET Operation")
This annotation describes the particular functionality a REST endpoint offers.

@ApiResponse(responseCode = "200", description = "Found the person", content = {@Content(mediaType = "application/json", schema = @Schema(implementation = Person.class))})
This annotation describes the API response.