MicroProfile OpenAPI for creating OpenAPI specifications

Last Updated:  October 11, 2020 | Published: August 24, 2019

Exposing REST endpoints usually requires documentation for your clients. This documentation usually includes the following: accepted media types, HTTP method, path variables, query parameters, and the request and response schema. With the OpenAPI v3 specification we have a standard way to document APIs. You can generate this kind of API documentation from your JAX-RS classes using  MicroProfile OpenAPI out-of-the-box. In addition, you can customize the result with additional metadata like detailed description, error codes, and their reasons, and further information about the used security mechanism.

Learn more about the MicroProfile OpenAPI specification, its annotations, and how to use it in this blog post.

Specification profile: MicroProfile OpenAPI

  • Current version: 1.1
  • GitHub repository
  • Latest specification document
  • Basic use case: Provide a unified Java API for the OpenAPI v3 specification to expose API documentation

Customize your API documentation with MicroProfile OpenAPI

Without any additional annotation or configuration, you get your API documentation with MicroProfile OpenAPI out-of-the-box. Therefore your JAX-RS classes are scanned for your @Produces, @Consumes, @Path, @GET etc. annotations to extract the required information for the documentation. For an introduction into JAX-RS, have a look at this specification overview.

If you have external clients accessing your endpoints, you usually add further metadata for them to understand what each endpoint is about. Fortunately, the MicroProfile OpenAPI specification defines a bunch of annotations you can use to customize the API documentation.

The following example shows a part of the available annotation you can use to add further information:

In this example, I'm adding a summary and description to the endpoint to tell the client what this endpoint is about. Furthermore, you can specify the different response codes this endpoint returns and give them a description if they are somehow different from the HTTP spec.

Another important part of your API documentation is the request and response body schema. With JSON as the current de-facto standard format for exchanging data, you and need to know the expected and accepted formats. The same is true for the response as your client needs information about the contract of the API to further process the result. This can be achieved with an additional MicroProfile OpenAPI annotation:

Within the @APIResponse annotation we can reference the response object with the schema attribute. This can point to your data transfer object class. Aforementioned Java class can then also have further annotations to specify which field is required and what are example values:

Access the created documentation

The MicroProfile OpenAPI specification defines a pre-defined endpoint to access the documentation: /openapi:

This endpoint returns your generated API documentation in the OpenAPI v3 specification format as text/plain.

Moreover, if you are using Open Liberty you'll get a nicelooking user interface for your API documentation. You can access it at http://localhost:9080/openapi/ui/. This looks similar to the Swagger UI and offers your client a way to explore your API and also trigger requests to your endpoints via this user interface:

microProfileOpenAPIUIOpenLiberty

microProfileOpenAPIExecutionOfApiCall

microProfileOpenAPIModelExplorer

YouTube video for using MicroProfile OpenAPI

Watch the following YouTube video of my Getting started with MicroProfile series to see MicroProfile OpenAPI in action:

You can find the source code for this blog post on GitHub.

Have fun using MicroProfile OpenAPI,

Phil

>