Adding an API Description Using OpenAPI
The value of an API, such as a RESTful service, depends to a large extent on how easy it is to consume. Good and easily accessible documentation is an important part of whether an API is useful. In this chapter, we will learn how we can use the OpenAPI Specification to document APIs that we can make externally accessible from a microservice landscape.
As we mentioned in Chapter 2, Introduction to Spring Boot, the OpenAPI Specification, previously known as the Swagger specification, is one of the most commonly used specifications when it comes to documenting RESTful services. Many of the leading API gateways have native support for the OpenAPI Specification. We will learn how to use the open source project springdoc-openapi to produce such documentation. We will also learn how to embed an API documentation viewer, Swagger UI viewer, which can be used both to inspect the API documentation and also to make requests to the API.
By the end...