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:
| 1 2 3 4 5 6 7 8 9 10 11 | @GET @Operation(summary = "Get all books", description = "Returns all available books of the book store XYZ") @APIResponse(responseCode = "404", description = "No books found") @APIResponse(responseCode = "418", description = "I'm a teapot") @APIResponse(responseCode = "500", description = "Server unavailable") @Tag(name = "BETA", description = "This API is currently in beta state") @Produces(MediaType.APPLICATION_JSON) public Response getAllBooks() { System.out.println("Get all books..."); return Response.ok(new Book("MicroProfile", "Duke", 1L)).build(); } |
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:
| 1 2 3 4 5 6 7 8 9 | @GET @APIResponse(description = "Book", content = @Content(mediaType = "application/json", schema = @Schema(implementation = Book.class))) @Path("/{id}") @Consumes({MediaType.APPLICATION_JSON, MediaType.APPLICATION_XML}) public Response getBookById(@PathParam("id") Long id) { return Response.ok(new Book("MicroProfile", "Duke", 1L)).build(); } |
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:
| 1 2 3 4 5 6 7 8 9 10 11 12 13 | @Schema(name = "Book", description = "POJO that represents a book.") public class Book { @Schema(required = true, example = "MicroProfile") private String title; @Schema(required = true, example = "Duke") private String author; @Schema(required = true, readOnly = true, example = "1") private Long id; } |
Access the created documentation
The MicroProfile OpenAPI specification defines a pre-defined endpoint to access the documentation: /openapi:
| 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 | openapi: 3.0.0 info: title: Deployed APIs version: 1.0.0 servers: - url: http://localhost:9080 - url: https://localhost:9443 tags: - name: BETA description: This API is currently in beta state paths: /resources/books/{id}: get: operationId: getBookById parameters: - name: id in: path required: true schema: type: integer format: int64 responses: default: description: Book content: application/json: schema: $ref: '#/components/schemas/Book' |
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 nice–looking 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:
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
