OpenAPI Docs and Swagger for your SpringBoot REST API/Micro Service

Hey peeps! Doing good??? Covid 19 pandemic problems may be still bothering you. What about trying out something different on the technologies we use? This is especially about REST API built with SpringBoot. Have you ever tried to create documentation for your API or MicroService? Today I'm going to show you how to create such a document easily with OpenAPI Docs. And not only that, we have a nice and clean prebuilt UI for the API if we use Swagger UI. So I will use both of these in the article with more explanations.

Setup a SpringBoot app

Create a new project with your favorite IDE plugins or from the https://start.spring.io/ website. After creating the project we need to include the maven dependency in our project. They are listed below.

https://mvnrepository.com/artifact/org.springdoc/springdoc-openapi-ui/1.5.2

Include the dependency in the pom.xml file.

<dependency>

    <groupId>org.springdoc</groupId>

    <artifactId>springdoc-openapi-ui</artifactId>

    <version>1.5.2</version>

</dependency>

Create REST API Endpoints

Let's create a simple API with 2 or 3 REST endpoints. You can follow the below codes and create them easily. Then only we can continue the rest of the article. Here I will use MongoDB as the data source. You can set the configurations like this in application.properties file.

server.port=8000

springdoc.api-docs.path=/item-docs #for open-api docs

spring.data.mongodb.host=localhost

spring.data.mongodb.database=item-store

spring.data.mongodb.port=27017

Controller

Service

Repository

Entity

Definition for Open API Docs

This is the most important part. I will explain how to specify some properties for the API docs that we are going to create. Open the file which runs your SpringBoot application via the main method. We need to define some properties here. Look at the below java file.

We use an annotation called @OpenAPIDefinition to let the application know that we are going to use Open API. Through that settings, we provide some information like title, version, description which should be referred to when the DOCS is created runtime.

I hope now we have a simple API with items. So you can test the API with Postman. I will not cover those here since I need to highlight the Open API in this article. So, just run the application and see.

We see the API suing postman or browser traditionally. What do you do if you need documentation with endpoints for your API??

Here Open API comes into the party guys!!!

You may have already seen that we included a configuration path in application.properties file. That is the path where we should navigate to see the docs in the browser. 

Open API dependency is creating that for us!!!

Just go to the below URL from the browser

http://localhost:8000/item-docs

What could you see?? A well formatted documentation with your API endpoints? If so, we have a nice and simple documentation guys. 

If you need to download the docs as a YAML file, just enter the below URL on the browser. Then it will be downloaded. 

http://localhost:8000/item-docs.yaml

Swagger UI

This is the next awesome part..Now we have a documentation file. Do you know, now we already have a nice User Interface/Web page to show our API to anyone? We do have peeps!!!!

Just enter the below URL and see!

http://localhost:8000/swagger-ui/index.html?configUrl=/item-docs/swagger-config

YOU GOT CONFUSED???

Most probably your answer may be YES! This is the magic. Now we have a nice web page to show how API works.

If you have created the API with me, now you must have 3 API endpoints. You can expand one by one from the UI and see about details. 

GET - list all items endpoint

POST - all an item endpont

You can add a request body and hit execute to see whether we can add an item from this UI.

When you add another API endpoint to the API, you should re-run the application. You will see the updated API interface from the browser.

Now do not need POSTMAN!

Try to use this awesome tool - Open-API to demonstrate your API endpoints to others. It will be a nice experience for you and the people who see the API in action!

Hope you got something new for your DEV LIFE guys! I will come back again when I found something interest on any tech topic guys! 

Till then, Good Bye and Stay Safe!