Documenting APIs with the OpenAPI Specification

In the previous chapter, we learned how to develop our Spring Boot application. First, we configured our application to run on the server using IntelliJ. Then, we developed the different parts of the REST application, such as the models and entities, which serve as the objects; the services, which hold the business logic and call the JPA repository to perform CRUD operations in the database; and the controllers, which define the endpoints. We also learned how to apply Redis, which adds a caching mechanism to improve the performance of our REST APIs.

This chapter will focus on creating the documentation for our Spring Boot project. We will focus on configuring springdoc-openapi and Swagger UI and generating documentation on the fly for the endpoints that we have developed.

In this chapter, we will cover the following topics:

• Setting up springdoc-openapi
• Setting up Swagger UI

Technical requirements

The following link will take you to the finished version of this chapter: https://github.com/PacktPublishing/Spring-Boot-and-Angular/tree/main/Chapter-06/superheroes.

Setting up springdoc-openapi

In this section, we will configure springdoc-openapi in our Spring Boot application. Since we developed our REST APIs in the previous chapter, the next thing we need to do is create documentation for our endpoints. This is an essential part, especially in the development industry, as this will tell the developers what endpoints can be implemented, what the required requests and their formats are, and what response body to expect when calling the endpoint. This also reduces errors and conflicts regarding the API integration as the available endpoints are transparent. However, the major drawback of creating documentation manually is that it is tedious and error-prone. This is where springdoc-openapi comes into the picture.

First, let’s discuss what springdoc-openapi is. springdoc-openapi is a library that automates the generation of API documentation in Spring Boot projects. This automation is possible as the library uses annotations, class structures...

Setting up Swagger UI

Swagger UI is a documentation tool that allows users to call the available APIs in your project directly from a browser. This is a more interactive tool that enables a more detailed and practical use of the APIs. Swagger UI is also open source, enabling more communities to support the tool.

Installing and using Swagger UI

Swagger UI is already included under the springdoc-openapi-ui dependency. We have already included the OpenAPI extension code by adding the following code:

<dependency>
      <groupId>org.springdoc</groupId>
      <artifactId>springdoc-openapi-ui</artifactId>
      <version>1.6.4</version>
</dependency>

The OpenAPI dependency includes the Swagger UI extension; we can access the UI with the following URL: http://localhost:8080/swagger-ui.html. This will open the Swagger UI’s OpenAPI definition...

Summary

With this, we have reached the end of this chapter. Let’s recap the valuable things you have learned.

First, you learned about the available features and properties of springdoc-openapi and how to configure and use the OpenAPI specification to generate the JSON and YAML documentation for our API calls. You also learned how to access Swagger UI, an interactive documentation tool for calling APIs directly in a browser. We simulated this to send test calls and modify certain behaviors, such as the domain URL and the sorting order. This newly acquired knowledge for generating documentation for APIs is very useful in real-world applications. This knowledge is used by developers to easily identify the available APIs that can be consumed, as well as their parameters and object responses.

In the next chapter, we will learn about the concept of Cross-Origin Resource Sharing (CORS), Spring Security, and JSON Web Tokens (JWTs).