Spring Boot RESTful API Documentation With Swagger

4 min readApr 26, 2020

In this article i am going to talk everything you need to know working with Swagger in a Spring Boot application. I will also talk about what Swagger is, and after that i will talk about integrating Swagger with Spring Boot application to generate API documentation. Let’s get started.

What is a Swagger?

> Tool to Develop API’s
> Interact with API’s and
> Document API’s

Swagger is quite popular for Documentation of APIs. It has various ways of documentation and the most popular way is using Swagger UI. When most people think about Swagger, they think about Swagger UI. But, Swagger is more than that. However, in this article i will be focusing on Documentation part of Swagger. We will learn how to document Spring Boot application using Swagger APIs.

Why to document API’s?

Consider a scenario, you are a Developer and you are developing some of the APIs. Now, you ask testing team to access and verify these APIs. First think they will ask is documentation, to understand how to use the API. The questions may be what are the End Points? What are the response codes that end points will provide? What are the methods? What is the payload structure they need to provide while making a request? What is the response structure they are going to get? What are the error conditions they might have to handle and many other questions. The quickest way to answer all these question is to prepare a documentation and write down all the details of your API and hand it over to them. But, do developers really has that much time to write and document all these of course NO. But, the major problem is even if they write this, what if API changes in future. So they can not keep on updating the documentation all the time. Also, they need to ensure that it is always in sync. So, this will become constant and consistent problem to solve.

Before REST the most popular API technology was SOAP, and SOAP has WSDL for documentation. However, REST API does not has any such strict requirement of documentation in the specification. In genera it is a good flexibility, but we still need something that can auto generate API documentation. This is where Swagger documentation tool comes into the picture. Swagger auto generates documentation based on Metadata in the code. So, developers just need to write Metadata and tool with generate documentation. If there is any change in API code, developer just need to update Metadata. So no more manual documentation or outdated documentation.

Steps to add Swagger to Spring Boot application

Step 1: Adding the Swagger 2 Spring Dependency in POM.XML file of the project.Swagger is an specification for the documentation and there are many implementations of this, we are going to use Spring implementation for now. As Swagger can be used with various other platforms in various other languages.

Step 2: Enable Swagger in your code.

Step 3: Configuring Swagger

Step 4: Adding more details as Annotations to the APIs. Kind of notes e.g. use this API for this purpose and add more information to the API.

Let us do it:

Create a Spring Boot application

I have created a basic Spring Boot REST based application that can take Get requests and returns the response. Here is my controller class code:

Now, let’s add springfox-swagger2 dependency in my POM file.

<!-- https://mvnrepository.com/artifact/io.springfox/springfox-swagger2 -->
<dependency>
    <groupId>io.springfox</groupId>
    <artifactId>springfox-swagger2</artifactId>
    <version>2.9.2</version>
</dependency>

Add another dependency “” that generates HTML documentation.

<!-- https://mvnrepository.com/artifact/io.springfox/springfox-swagger-ui -->
<dependency>
    <groupId>io.springfox</groupId>
    <artifactId>springfox-swagger-ui</artifactId>
    <version>2.9.2</version>
</dependency>

Next step is to enable Swagger 2, this is straightforward, you just need to use an @EnableSwagger2 annotation in the main class.

Add, @RequestMapping(“/api”) in the controller class to allow all requests to get in and let Swagger UI handle at the root URL.

Once done, just restart the server.

Navigate to “http://localhost:8080/spring-boot-hello-user/swagger-ui.html#/” url and you will see Swagger UI and it’s glory.

Expand the APIs exposed on this page and it provide more details. You can try it out from here. You can click on one of the Get request and make the API calls. After execution you will get the Get response that you can read on this HTML page. You don’t need Postman anymore.

So in this way any one who need documentation can point to the URL and get it. Moreover nobody needs to write the documentation now manually. I hope this was useful.

GIT for the source code:

https://github.com/raghwendra-sonu/Swagger_Ingegration_With_SpringBootApp

Let me know if this was helpful. If you ever need my help, you can write in comments sections. Also, you can contact me through my LinkedIn Profile.