[JAVA] J'ai essayé Eclipse MicroProfile OpenAPI avec WildFly Swarm
Motivation
Depuis qu'Eclipse MicroProfile 1.3 a été ajouté dans WildFly Swarm 2018.3.3, je voulais essayer MicroProfile OpenAPI 1.0, qui est l'une des spécifications de MicroProfile 1.3.
La spécification OpenAPI est l'ancienne spécification Swagger
** Spécification OpenAPI ** (OAS) était autrefois ** Spécification Swagger ** et est un produit de SmartBear [Swagger](https: // swagger) Ce qui était censé être .io /) a été donné à la ** OpenAPI Initiative ** (un projet conjoint de la Linux Foundation) et est devenu une spécification publique. Si vous disposez de YAML ou JSON conforme aux spécifications OpenAPI, vous pouvez créer une référence d'API REST et générer des implémentations d'API REST pour chaque langage.
Qu'est-ce que MicroProfile OpenAPI 1.0?
Avec ** MicroProfile OpenAPI 1.0 ** ajouté à MicroProfile 1.3 cette fois, lorsque vous créez une ressource JAX-RS, ses spécifications sont automatiquement fournies en YAML ou JSON. En d'autres termes, dans un premier temps, la conception (document) détermine d'abord les spécifications de l'API avec YAML d'OAS, et même si les spécifications sont modifiées après être tombées dans le code, elles peuvent être directement reflétées dans le document de l'API, il est donc possible de réécrire les spécifications. Il disparaît.
Choses à faire. Ce que j'ai fait.
Cette fois, je vais créer une ressource JAX-RS avec WildFly Swarm 2018.3.3 avec un codage en premier et vérifier que la spécification compatible OpenAPI (YAML) est générée.
Génération de projet
Si vous allez à http://wildfly-swarm.io/generator/ et entrez MicroProrfile dans le formulaire Dependencies, MicroProfile OpenAPI Fraction sera suggéré, alors sélectionnez et sélectionnez "Generate Project". Appuyez sur pour télécharger le projet WildFly Swarm (fichier zip) avec MicroProfile.
Construire et démarrer
Décompressez simplement le zip téléchargé et construisez-le, et cela fonctionne déjà comme une application JAX-RS.
Extrayez le zip téléchargé et compilez
unzip demo.zip
cd demo
mvn package
Lorsque vous le construisez, un fichier JAR (Uber JAR) qui peut être utilisé est créé sous la cible, alors démarrez-le avec la commande java.
Lancez l'application intégrée
java -jar target/demo-swarm.jar
Essayez d'accéder à l'application lancée
Allez sur http: // localhost: 8080 / hello et vous obtiendrez "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!
En fait, à ce stade, les spécifications de cette API ont été publiées. Si vous visitez http: // localhost: 8080 / openapi, vous obtiendrez un fichier au format YAML conforme à la spécification OpenAPI. Il s'agit de la ** spécification API **.
$ 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: {}
Rendre la page facile à voir pour les internautes
Cela seul n'est pas illisible en tant que spécification d'API, mais ce n'est pas convivial pour les gens, donc je le rendrai lisible en tant que document correctement. À la suite de diverses enquêtes, ReDoc semble être bon. La référence API pour Docker Engine semble également l'utiliser.
Changer le chemin JAX-RS
Je veux mettre du HTML, mais comme le chemin racine est le chemin JAX-RS par défaut, changez-le en / api.
JaxRsActivator.java
// package,importation omise
@ApplicationPath("api")
public class JaxRsActivator extends Application {
}
Cela change la ressource / hello en / api / hello.
Créer du HTML pour ReDoc
Il est également écrit dans ReDoc README.md, mais je mettrai un fichier HTML comme suit.
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>
<!--ici/Je vais me référer à openapi!-->
<redoc spec-url='/openapi'></redoc>
<script src="https://cdn.jsdelivr.net/npm/redoc@next/bundles/redoc.standalone.js"></script>
</body>
</html>
Après cela, si vous le reconstruisez de la même manière et le démarrez 。 Les ressources JAX-RS sont fournies à l'adresse http: // localhost: 8080 / api / hello Vous pouvez voir le YAML conforme à la spécification OpenAPI sur http: // localhost: 8080 / openapi Sur http: // localhost: 8080 /, vous avez un document API sympa!
Si vous souhaitez définir diverses informations telles que le titre, la licence, les coordonnées, etc. src / main / resources / META-INF / openapi.json [Format selon la spécification OpenAPI](https://github.com/OAI/ Si vous le modifiez avec la spécification OpenAPI-Specification / blob / master / versions / 3.0.1.md #), il sera reflété sur la page.
Pour améliorer encore la documentation
Le MicroProfile OpenAPI fournit diverses annotations. Si vous l'attachez correctement à la ressource JAX-RS, vous pouvez ajouter des informations conformes à la spécification OpenAPI.
De plus, en définissant Extension correspondant à ReDoc, l'API Il semble que vous puissiez ajouter la fonction pour générer un exemple de code pour le client et ajouter des informations telles que l'exemple JSON à POST.
Code fait pour la démo
Il est publié sur GitHub https://github.com/sightseeker/wildfly-swarm-mp-demo, donc si vous voulez l'essayer immédiatement, veuillez cliquer ici.
Files
C'est le seul fichier.
├── pom.xml
└── src
└── main
├── java/com/sightseekerstudio/wildflyswarmmpdemo/rest
│ ├── HelloWorldEndpoint.java
│ └── JaxRsActivator.java
├── resources
│ └── META-INF
│ └── openapi.json
└── webapp
└── index.html
Recommended Posts