The mobile force that fuels the digital economy led to the need for businesses to establish an omni-channel approach to development in order to optimize costs, increase efficiencies, and improve customer experience. A facilitator of this approach was APIs, which led to the API economy and concepts such as API-led or API-first development practices. In addition, the microservices architecture has become the architecture of choice for modern development. API-based (that is, RESTful) communication among microservices has been adopted as the de facto standard because it is a good fit for the smart endpoints and dumb pipes, decentralized governance, and decentralized data management characteristics of microservices.
However, as the number of microservices increases in a microservices architecture, their management can become unwieldy. However, you can manage your microservices via their APIs. You can apply management, security, load balancing, and throttling policies to the APIs that are fronting your microservices.
Eclipse MicroProfile OpenAPI provides Java interfaces to developers for generating OpenAPI v3 documents from their Java RESTful Web Services (JAX-RS) applications. The specification requires that a fully processed OpenAPI document be available at the root URL, /openapi, as an HTTP GET operation, as follows:
GET http://myHost:myPort/openapi
The required protocol is http. However, implementors of the specification are strongly encouraged to also support the https protocol for secure connectivity to the OpenAPI endpoint.
There are three sources from which the OpenAPI document is created. These three sources (described in later sections in this chapter) are as follows:
- Generated by processing the JAX-RS annotations (and optional OpenAPI annotations) found in the application
- Programmatically built by an application by providing a Java class that implements OasModelReader
- A static OpenAPI document included in application deployment
These three sources (any combination) are combined to produce a single OpenAPI document, which can be filtered (by providing a Java class that implements the OasFilter interface) and then served at the preceding /openapi endpoint.