Spring Boot and Swagger — Writing Good API Documentations

Documentations made easy

APIs are one of the key players in the technology world whether they are used in a simple mobile application in integrating complex enterprise systems. Any application can become a platform by enabling methods to enhance and add services to existing products using APIs.

Having good documentation for these APIs is critical to their success. API documentation is technical content that includes instructions on using and integrating the APIs. Think of it as a reference manual with all of the information you need to work with the API, like the request and response format, and how to start working with them.

You can always have your format of documentation for your APIs, but having a standard or a common format will make it more readable. Using good practices like Spec-driven development (SDD) also can help in keeping documentation effective. There are several specifications to get started with documenting, such as RAML (RESTful API Modeling Language), OpenAPI (formerly Swagger), and API Blueprint, but in this article, we will focus on OpenAPI and Swagger for Spring Boot Applications.

What is Swagger?

Swagger is a set of open-source tools that help you to describe REST-based APIs. This gives you the luxury to automatically build beautiful and interactive API documentation, automatically generate client libraries for your API in many languages, and explore other possibilities like automated testing.

Getting Started

To begin working with OpenAPI and creating your first swagger document you will need the following dependency in your application.

<dependency>     
    <groupId>io.springfox</groupId>     
    <artifactId>springfox-boot-starter</artifactId>
    <version>3.0.0</version>
</dependency>

Having version 3.0.0 of the starter make sure you have the compatible version of the starter parent dependency. in my…