Skip to content

Latest commit

 

History

History
160 lines (134 loc) · 4.75 KB

README.adoc

File metadata and controls

160 lines (134 loc) · 4.75 KB
Raw

microprofile-openapi: MicroProfile OpenAPI QuickStart

This guide demonstrate how to use the MicroProfile OpenAPI functionality in {productName} 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+

Steps

Access the OpenAPI documentation of the quickstart application

Run following command in your terminal:

$ curl http://localhost:8080/openapi

It 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
paths:
  /:
    get:
      responses:
        "200":
          description: OK
          content:
            text/plain:
              schema:
                type: string
  /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, {productName} 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.

  1. 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

  2. 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

  3. Rebuild and redeploy the modified sample application.

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