I tried Eclipse MicroProfile OpenAPI with WildFly Swarm

Motivation

With the addition of Eclipse MicroProfile 1.3 in WildFly Swarm 2018.3.3, I wanted to try MicroProfile OpenAPI 1.0, which is one of the MicroProfile 1.3 specifications.

OpenAPI Specification is the former Swagger Specification

** OpenAPI Specification ** (OAS) was once ** Swagger Specification ** and is a product of SmartBear Swagger What was supposed to be .io /) was donated to the ** OpenAPI Initiative ** (a joint project of the Linux Foundation) and has become a public specification. If you have YAML or JSON that conforms to the OpenAPI Specification, you can create a REST API reference or generate a REST API implementation for each language.

What is MicroProfile OpenAPI 1.0?

In ** MicroProfile OpenAPI 1.0 ** added to MicroProfile 1.3 this time, when you create a JAX-RS Resource, its specification is automatically provided as YAML or JSON. In other words, at first, the API specifications are decided by YAML of OAS in the design (document) first, and even if the specifications are changed after falling into the code, it can be directly reflected in the API document, so it is possible to rewrite the specifications. It disappears.

things to do. What I did.

This time, I will create a JAX-RS Resource with WildFly Swarm 2018.3.3 with coding first and check that the OpenAPI compliant specification (YAML) is generated.

Project generation

Go to http://wildfly-swarm.io/generator/ and type MicroProrfile in the Dependencies form, and the MicroProfile OpenAPI Fraction will be suggested, select" Generate Project ". Press to download the WildFly Swarm project (zip file) with MicroProfile.

Build and start

Simply unzip the downloaded zip and build it, and it will already function as a JAX-RS app.

`Unzip the downloaded zip and build`


unzip demo.zip
cd demo
mvn package

When you build it, a JAR file (Uber JAR) that can be specified is created under target, so start it with the java command.

`Launch the built app`


java -jar target/demo-swarm.jar

Try to access the launched app

Go to http: // localhost: 8080 / hello and you'll get Hello from WildFly Swarm!

$ curl -i http://localhost:8080/hello                                                                                                  [03/24 15:15]
HTTP/1.1 200 OK
Connection: keep-alive
Content-Type: text/plain;charset=UTF-8
Content-Length: 25
Date: Sat, 24 Mar 2018 06:17:20 GMT

Hello from WildFly Swarm!

Actually, at this point, the specifications of this API have been released. If you access http: // localhost: 8080 / openapi, you will get an OpenAPI Specification compliant YAML format file. This is the ** API specification **.

$ curl -i http://localhost:8080/openapi
---
openapi: 3.0.1
info:
  title: MicroProfile OpenAPI with WildFly Swarm
  description: This is a sample server for a MicroProfile OpenAPI.
  version: 1.0.0-SNAPSHOT
paths:
  /hello:
    get:
      responses:
        200:
          content:
            text/plain: {}

Make the page easy for people to see

This alone is not unreadable as an API specification, but it is not human-friendly, so I will make it readable as a document properly. As a result of various investigations, ReDoc seemed to be good. The API reference for Docker Engine also seems to use this.

Change the JAX-RS path

I want to put HTML, but since the root path is the JAX-RS path by default, change it to / api.

`JaxRsActivator.java`


// package,import omitted

@ApplicationPath("api")
public class JaxRsActivator extends Application {

}

This will change the / hello resource to / api / hello.

Create HTML for ReDoc

It is also written in README.md of ReDoc, but I will put one HTML file as follows.

`src/main/webapp/index.html`


<!DOCTYPE html>
<html>
    <head>
        <title>ReDoc</title>
        <!-- needed for adaptive design -->
        <meta charset="utf-8"/>
        <meta name="viewport" content="width=device-width, initial-scale=1">
        <link href="https://fonts.googleapis.com/css?family=Montserrat:300,400,700|Roboto:300,400,700" rel="stylesheet">
        <!--
        ReDoc doesn't change outer page styles
        -->
        <style>
            body {
                margin: 0;
                padding: 0;
            }
        </style>
    </head>
    <body>
    <!--here/I'll refer to openapi!-->
    <redoc spec-url='/openapi'></redoc>
    <script src="https://cdn.jsdelivr.net/npm/redoc@next/bundles/redoc.standalone.js"></script>
</body>
</html>

After that, if you rebuild in the same way and start it 。 JAX-RS resources are provided at http: // localhost: 8080 / api / hello You can see OpenAPI Specification compliant YAML at http: // localhost: 8080 / openapi At http: // localhost: 8080 /, you have a cool API document!

If you want to set various information such as title, license, contact information, etc. src / main / resources / META-INF / openapi.json [Format according to OpenAPI Specification](https://github.com/OAI/ If you modify it with OpenAPI-Specification / blob / master / versions / 3.0.1.md # specification), it will be reflected on the page.

To further enhance the documentation

MicroProfile OpenAPI provides various annotations If you attach it to JAX-RS Resource properly, you can add OpenAPI Specification compliant information.

Furthermore, by setting Extension corresponding to ReDoc, API It seems that you can add the function to generate sample code for the client, and add information such as JSON example to POST.

Code made for demo

It is posted on GitHub https://github.com/sightseeker/wildfly-swarm-mp-demo, so if you want to try it immediately, please click here.

Files

This is the only file.

├── pom.xml
└── src
    └── main
        ├── java/com/sightseekerstudio/wildflyswarmmpdemo/rest
        │   ├── HelloWorldEndpoint.java
        │   └── JaxRsActivator.java
        ├── resources
        │   └── META-INF
        │       └── openapi.json
        └── webapp
            └── index.html