Jakarta EE Tutorials, MicroProfile Tutorials

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:

@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();
}

@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:

@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();
}

@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:

@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;

}

@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:

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'

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: