RESTful API Documentation Made Easy with Swagger and OpenAPI
By: Somnath Musib
Tags: JavaScript, Software Development, Technology, Software Engineering, Programming

Swagger in Action

Now that we have understood what OpenAPI and Swagger are, let us see these in action. As part of this article, we will develop a REST application. We will then use Swagger UI to render our API documentation. Following that, we access the API document (available in JSON format) through Swagger Editor. Lastly, we will use Swagger Codegen CLI to generate a server and a client stub to demonstrate how one can use an OpenAPI document to mock the REST web services.

What are we building?

We will build a Spring Boot application that offers us to manage blood donors. It allows us to create, update, delete and view donor information.

Refer to this link for a step by step guide on how to set up the application in a development environment. Complete source code can be downloaded from this Github repository.

Following are the summary of steps:-

Create a new Spring boot application with JPA, H2 and Web dependencies

Create the model, service and the controllers

Run the application and try accessing various endpoints & its operations

Below is the application pom file:

pom.xml file

We have added the following two additional dependencies from io.springfox to enable Swagger 2 and Swagger UI:-

<dependency>

<groupId>io.springfox</groupId>

<artifactId>springfox-swagger2</artifactId>

<version>2.9.2</version>

</dependency>

<dependency>

<groupId>io.springfox</groupId>

<artifactId>springfox-swagger-ui</artifactId>

<version>2.9.2</version>

</dependency>

Swagger Configuration

Now that the project is up & running and we can access our REST endpoints, let us add the swagger configuration:-

Swagger Configuration

This is a Spring configuration with Swagger documentation information. We have added metadata information about the REST API such as API name, author, website, license and so on. We have also instructed Swagger to only generate documentation for the components present in the io.codefountain.swagger package.

Accessing Swagger UI

Since we have enabled Swagger, let us see the documentation of our API endpoints done by Swagger. This is rendered through Swagger UI in the following link:

http://localhost:8080//swagger-ui.html#/donor-controller

Swagger default documentation

Swagger has put together the following information:-

Document metadata (API name, license, website, contact and so on)

All REST endpoints with default information it can infer from code. Note that endpoint descriptions are method names

These are the default information. Let us now explicitly document of our API with swagger annotations to provide a detailed description and information about the endpoints and operations.

Documenting Rest Controller

As discussed, we will now document the REST controller explicitly. Swagger provides several annotations to add documentation metadata that it pulls while generating the documentation.

For each of the REST endpoint and its associated operations, we have provided ApiOperation and their various responses with ApiResponses annotations.

REST controller with explicit documentation

Restart the application and access the same URL:

Updated Swagger documentation

This time, Swagger has pulled the information supplied through the annotations. Not only this, it has now added explicit response information with HTTP response codes:-

API documentation with HTTP response code

Accessing Swagger Editor

So far we have accessed the API documentation locally. Swagger also generates the documentation in the JSON file format adhering to the OpenAPI specification. We can share this JSON file with the consumers and they can read the endpoint information, generate client and server stubs.

Our REST API documentation can be accessed through the following URL:-

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

api-docs.json

This JSON document conforms OpenAPI specification and can be accessed through Swagger Editor as shown below:-

API Document in Swagger Editor

Anyone with access to this document can view the API endpoints and all other related metadata such as model structure, data types and so on.