Why document APIs?

Documenting an API is essential for its effective utilization by consumers. In plain terms, the documentation tells the user what the API does and how it is to be used. Specific provisions of the documentation include invocation syntax, description, testing, examples and references regarding the API

Why OpenAPI?

OpenAI provides a specification for dynamic API documentation. This means that you implement the specification once in your code and get automatic updates to your API documentation, when your code changes, for free. In addition, the documentation can be viewed and interacted with via a visualization tool displayed in the browser.

Swagger is the name of one of the most utilized tools in the OpenAPI specifications. The Swagger tools provide several functionalities which can be explored in the link https://swagger.io/resources/open-api/. For this article, we would be utilizing the Swagger UI for the API visualization

The code sample of this article will make use of Spring Boot 3.0 and the OpenAPI version 2.1.0 (which is recommended for Spring Boot 3.0)

Code steps

1. Target project

   An already existing ‘Items’ API with endpoints for: Getting all items, getting items by id and posting new items, will be used. You will use any API that you want to document

2. Dependencies (Maven)

   First off, add the following dependency to the pom file. This is the only dependency required:

    <dependency>
       <groupId>org.springdoc</groupId>
       <artifactId>springdoc-openapi-starter-webmvc-ui</artifactId>
       <version>2.0.4</version>
    </dependency>
   

3. Implementing in the Application file

• In the Applications file, add the annotation @OpenAPIDefintion before the class definition

• Provide the info object as shown below with the required metadata. A full list of supported metadata can be found in the specification link https://swagger.io/specification/. See code sample below:

import io.swagger.v3.oas.annotations.info.Contact;
import io.swagger.v3.oas.annotations.info.Info;
import org.springframework.boot.SpringApplication;
import org.springframework.boot.autoconfigure.SpringBootApplication;

@SpringBootApplication
@OpenAPIDefinition(info=@Info (title = "Items API",
      version = "1.0",
      description = "This is a demonstration for items",
      termsOfService = "https://www.kolabank.com",
      contact = @Contact(name = "Bamky", url="kolabank.com", email = "kolabank@gmail.com")))

public class ArticlesApplication {

1. Accessing the API documentation

• Viewing in Swagger-UI

Run the application and go to the URL http://server:port/context-path/swagger-ui.html. For example, for development on a local computer, the path might be localhost:8080/swagger-ui.html

The Swagger UI API document page, as seen in the figure below would be displayed. Clicking on any of the endpoints will display the parameters

• Viewing the OpenAPI description

  The OpenAPI description (plain text) can be viewed by using the route: server:port/context-path/v3/api-docs. For example, using a locally running development server, this path can be localhost:8080/v3/api-docs

• Downloading the yaml file

  To download the yaml file of the OpenAPI description, append .yaml to the path for viewing the OpenAPI description

Customizing the API description route

To customize the OpenAPI description route, introduce a preferred route by assigning the springdoc.api-docs.path in the properties file. You can now view the description by replacing '/v3/api-docs' with the specified route

springdoc.api-docs.path=/itemdocs

Conclusion

The OpenAPI specification provides an easy-to-use tool for API documentation. The dynamic nature of its operation enables the implementation to be carried out once-for-all in a project