One of the new features in Payara Platform version 5.182 is full compatibility with MicroProfile 1.3. In this blog post, I will introduce OpenAPI 1.0, a new API in MicroProfile 1.3. This functionality is available in both Payara Server and Payara Micro in version 5.182. It's also available in version 18.104.22.168 for Payara Support customers.
What is OpenAPI?
The OpenAPI specification itself is unrelated to MicroProfile. It's a specification designed to provide a standard format for documenting REST API services. An OpenAPI document looks similar to the following:
This document contains things such as:
- a list of common objects
- a list of servers the API is available from
- a list of each path in the API as well as what parameters it accepts
This document is extremely useful since, as it follows a standard, it can be used in a range of tools such as those provided by the Swagger suite. These let you do all sorts of things such as design, edit and test a REST API documented by an OpenAPI document.
How Does This Relate to MicroProfile?
MicroProfile designed the MicroProfile OpenAPI specification to extend the general OpenAPI specification and integrate it into MicroProfile applications. The specification states that any implementing servers should host an endpoint at
/openapi which will provide an OpenAPI document built from a deployed application. When you deploy an application, this document will be built automatically according to the application contents. The document can then be edited or used however you like. The specification also illustrates a few methods of editing this document. You could for example add a description to an endpoint, or a new title for the document so that the document hosted at the
/openapi endpoint appears in any way you like.
How Can I Use MicroProfile OpenAPI in the Payara Platform?
No configuration is needed for the OpenAPI implementation in the Payara Platform, you need just deploy an application! The OpenAPI is included in Payara Micro and Payara Server, so which one you use doesn't matter. For a full example of the usage, see the specification documentation.
Let's say you deployed an application with only the following classes:
With this application deployed, visiting http://localhost:8080/openapi/ will produce the following document:
This is useful, but not as useful as it could be. Often you'll want descriptions, and more in depth descriptors for the objects in the application (more similar to the first document in this blog). There are various ways of doing this. Each of the following configuration sources are applied in order:
- Configuration properties provided via the MicroProfile Config API. This allows you to do lots from disabling application scanning to including extra servers in the document.
OASModelReaderimplementation in the application. This provides a base document to be built upon for the final output.
- A static OpenAPI document provided in the application. This does the same as the former, but in a slightly different format.
- Annotations on the endpoint methods or object classes. This is the most idiomatic way of editing the document with minor changes.
OASFilterimplementation in the application. This will visit each element in the document and either remove it or edit it programmatically.
A brief example of each can be seen below. For a more detailed example utilising each of these, see the following example: https://github.com/payara/Payara-Examples/tree/master/microprofile/openapi-example.
The MicroProfile OpenAPI specification includes a few properties for the MicroProfile Config API. These can be included from any of the sources defined in the MicroProfile Config API. For example, in a config file stored in
An example configuration property might look as follows:
OASModelReader and OASFilter Implementations
MicroProfile OpenAPI provides two interfaces for the application developer to implement:
Each of these have a similar function, but are applied at different times. An implementation of
OASModelReader will create an initial OpenAPI document to build the final document from. An implementation of
OASFilter will be used to visit every object in the OpenAPI document before it is published. This allows final configuration changes to be made.
When implementing each of these, the relevant interface should be implemented, and a config property should be specified in the Config API (often in
A Static OpenAPI Document
A static OpenAPI document file can be placed in
src/main/resources/META-INF and called any of
openapi.json (and represented in the appropriate format of YAML or JSON). When this happens, this document will be used before any application processing. This means that if you want, you can take the document produced by the application initially, then remove any OpenAPI annotations present, edit the document as you wish and place it in the resources folder again to produce the same output!
MicroProfile OpenAPI defines several annotations that can be used to augment the produced OpenAPI document. These are detailed in the MicroProfile OpenAPI specification, but an example of them is as follows:
This helps make small tweaks to the produced document, and in the most non-intrusive way of editing the output.
The OpenAPI service in Payara Platform
The OpenAPI service is enabled by default in Payara Server and Payara Micro. The service can be controlled by two new asadmin commands. These need very little explanation, so here they are for reference!
When the OpenAPI service is disabled, no applications deployed during this period will have OpenAPI documents produced, and the endpoint will return a 403 response. A quirk of the service is that when it is enabled again, any applications deployed before it was disabled will still have their document shown, whereas any deployed while it was disabled will need redeploying. Outside of this functionality, the most recently deployed application will have it's OpenAPI document shown.
A Laid-Back Approach to REST Documentation
The new MicroProfile Open API service in Payara Platform enables building and serving OpenAPI documents out of the box. Before the OpenAPI implementation, documents would have to be produced manually, or using an external tool and hosted as part of the application. This new integration eases the production of the document, and makes it feel more native to a MicroProfile application.