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.

image.png

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!

image.png

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

Recommended Posts

I tried Eclipse MicroProfile OpenAPI with WildFly Swarm
I tried hot reloading with DevTools from Thorntail (formerly WildFly Swarm)
I tried UPSERT with PostgreSQL.
I tried BIND with Docker
I tried using JOOQ with Gradle
I tried morphological analysis with MeCab
I tried to interact with Java
I tried UDP communication with Java
I tried GraphQL with Spring Boot
I tried Flyway with Spring Boot
I tried customizing slim with Scaffold
I tried to build an http2 development environment with Eclipse + Tomcat
I tried using Realm with Swift UI
I tried to get started with WebAssembly
I tried using Scalar DL with Docker
Get in touch with Eclipse MicroProfile Health
I want to use DBViewer with Eclipse 2018-12! !!
I tried using OnlineConverter with SpringBoot + JODConverter
I tried time-saving management learning with Studyplus.
I tried playing with BottomNavigationView a little ①
I tried using OpenCV with Java + Tomcat
I tried Lazy Initialization with Spring Boot 2.2.0
I tried to implement ModanShogi with Kinx
[For beginners] I tried using DBUnit in Eclipse
I tried to verify AdoptOpenJDK 11 (11.0.2) with Docker image
I tried to make Basic authentication with Java
I tried to manage struts configuration with Coggle
[For beginners] I tried using JUnit 5 in Eclipse
I also tried WebAssembly with Nim and C
I made blackjack with Ruby (I tried using minitest)
I tried to break a block with java (1)
I tried Getting Started with Gradle on Heroku
I tried Spring.
I tried tomcat
I tried youtubeDataApi.
I tried refactoring ①
I tried FizzBuzz.
I tried JHipster 5.1
I tried what I wanted to try with Stream softly.
I tried to implement file upload with Spring MVC
I tried to read and output CSV with Outsystems
I tried to implement TCP / IP + BIO with JAVA
[Java 11] I tried to execute Java without compiling with javac
[Rails] I tried playing with the comment send button
I started MySQL 5.7 with docker-compose and tried to connect
[Machine learning] I tried Object Detection with Create ML [Object detection]
I tried to draw animation with Blazor + canvas API
I tried OCR processing a PDF file with Java
I tried to implement Stalin sort with Java Collector
roman numerals (I tried to simplify it with hash)