microprofile-openapi: MicroProfile OpenAPI QuickStart

This guide demonstrate how to use the MicroProfile OpenAPI functionality in JBoss EAP XP to expose an OpenAPI document for a simple REST application.

Prerequisites

To complete this guide, you will need:

less than 15 minutes
JDK 1.8+ installed with JAVA_HOME configured appropriately
Apache Maven 3.5.3+

Use of the EAP_HOME and QUICKSTART_HOME Variables

In the following instructions, replace EAP_HOME with the actual path to your JBoss EAP XP installation. The installation path is described in detail here: Use of EAP_HOME and JBOSS_HOME Variables.

When you see the replaceable variable QUICKSTART_HOME, replace it with the path to the root directory of all of the quickstarts.

Steps

Start the JBoss EAP XP Standalone Server

Open a terminal and navigate to the root of the JBoss EAP XP directory.
Start the JBoss EAP XP server with the MicroProfile profile by typing the following command.
```
$ EAP_HOME/bin/standalone.sh -c standalone-microprofile.xml
```
Note
For Windows, use the EAP_HOME\bin\standalone.bat script.

Build and Deploy the Quickstart

Make sure you start the JBoss EAP XP server as described above.
Open a terminal and navigate to the root directory of this quickstart.
Type the following command to build the artifacts.
```
$ mvn clean package wildfly:deploy
```

This deploys the microprofile-openapi-quickstart/target/microprofile-openapi-quickstart.war to the running instance of the server.

You should see a message in the server log indicating that the archive deployed successfully.

Access the OpenAPI documentation of the quickstart application

$ curl http://localhost:8080/openapi

+ Which should return a YAML document conforming to the OpenAPI specification:

openapi: 3.0.1
info:
  title: Store inventory
  description: Application for tracking store inventory
  version: "1.0"
servers:
- url: /microprofile-openapi-quickstart
paths:
  /inventory/fruit:
    get:
      responses:
        "200":
          description: OK
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/Fruit'
    post:
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/Fruit'
      responses:
        "200":
          description: OK
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/Fruit'
    delete:
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/Fruit'
      responses:
        "200":
          description: OK
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/Fruit'
components:
  schemas:
    Fruit:
      type: object
      properties:
        description:
          type: string
        name:
          type: string

Enhance OpenAPI documentation with annotations

You can further enhance/complete your OpenAPI documentation by adding MicroProfile OpenAPI annotations. You will need to rebuild/redeploy for those changes to be reflected in the OpenAPI document.

Finalizing OpenAPI documentation

Rather than processing JAX-RS and MicroProfile OpenAPI annotations every time an application is deployed, JBoss EAP XP can be configured to serve a static OpenAPI document. When serving a static document, typically, we also want to disable annotation processing. This is generally suggested for production environments, to ensure an immutable/versioned API contract for integrators.

Save the generated document to the source tree. Feel free to use JSON, if you prefer that over YAML.

$ mkdir src/main/webapp/META-INF
$ curl http://localhost:8080/openapi?format=JSON > src/main/webapp/META-INF/openapi.json

Reconfigure the application to skip annotation scanning when processing the OpenAPI document model.
```
$ echo "mp.openapi.scan.disable=true" > src/main/webapp/META-INF/application.properties
```
Rebuild and redeploy the modified sample application.

The OpenAPI document model will now be built from the static content rather than annotation processing.

Undeploy the Quickstart

When you are finished testing the quickstart, follow these steps to undeploy the archive.

Make sure you start the JBoss EAP XP server as described above.
Open a terminal and navigate to the root directory of this quickstart.
Type this command to undeploy the archive:
```
$ mvn wildfly:undeploy
```