[JAVA] Ich habe Eclipse MicroProfile OpenAPI mit WildFly Swarm ausprobiert
Motivation
Da Eclipse MicroProfile 1.3 in WildFly Swarm 2018.3.3 hinzugefügt wurde, wollte ich MicroProfile OpenAPI 1.0 ausprobieren, eine der Spezifikationen von MicroProfile 1.3.
Die OpenAPI-Spezifikation ist die frühere Swagger-Spezifikation
** OpenAPI Specification ** (OAS) war einmal ** Swagger Specification ** und ist ein Produkt von SmartBear [Swagger](https: // swagger) Was eigentlich .io /) sein sollte, wurde der ** OpenAPI Initiative ** (einem gemeinsamen Projekt der Linux Foundation) gespendet und ist zu einer öffentlichen Spezifikation geworden. Wenn Sie über YAML oder JSON verfügen, das den OpenAPI-Spezifikationen entspricht, können Sie eine REST-API-Referenz erstellen und REST-API-Implementierungen für jede Sprache generieren.
Was ist MicroProfile OpenAPI 1.0?
Wenn ** MicroProfile OpenAPI 1.0 ** dieses Mal zu MicroProfile 1.3 hinzugefügt wird, werden beim Erstellen einer JAX-RS-Ressource die Spezifikationen automatisch als YAML oder JSON bereitgestellt. Mit anderen Worten, beim ersten Entwurf (Dokument) wird zuerst die API-Spezifikation von YAML von OAS festgelegt. Selbst wenn die Spezifikation nach dem Einfügen in den Code geändert wird, kann sie direkt im API-Dokument wiedergegeben werden, sodass die Spezifikation neu geschrieben werden kann. Es verschwindet.
Dinge die zu tun sind. Was ich getan habe.
Dieses Mal werde ich mit WildFly Swarm 2018.3.3 eine JAX-RS-Ressource mit Codierung erstellen und überprüfen, ob die OpenAPI-kompatible Spezifikation (YAML) generiert wurde.
Projektgenerierung
Gehen Sie zu http://wildfly-swarm.io/generator/ und geben Sie "MicroProrfile" in das Formular "Abhängigkeiten" ein. Die "MicroProfile OpenAPI-Fraktion" wird vorgeschlagen. Wählen Sie "Projekt generieren" aus. Drücken Sie, um das WildFly Swarm-Projekt (Zip-Datei) mit MicroProfile herunterzuladen.
Bauen und starten
Entpacken Sie einfach die heruntergeladene Zip-Datei und erstellen Sie sie. Sie funktioniert bereits als JAX-RS-App.
Extrahieren Sie die heruntergeladene Zip-Datei und erstellen Sie sie
unzip demo.zip
cd demo
mvn package
Nach dem Erstellen wird unter target eine JAR-Datei (Uber JAR) erstellt, die verwendet werden kann. Starten Sie sie daher mit dem Befehl java.
Starten Sie die erstellte App
java -jar target/demo-swarm.jar
Versuchen Sie, auf die gestartete App zuzugreifen
Gehen Sie zu http: // localhost: 8080 / hello und Sie erhalten "Hallo von 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!
Zu diesem Zeitpunkt wurden die Spezifikationen dieser API veröffentlicht. Wenn Sie http: // localhost: 8080 / openapi besuchen, erhalten Sie eine Datei im YAML-Format, die der OpenAPI-Spezifikation entspricht. Dies ist die ** API-Spezifikation **.
$ 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: {}
Machen Sie die Seite für die Leute leicht sichtbar
Dies allein ist als API-Spezifikation nicht unlesbar, aber nicht benutzerfreundlich, sodass ich es als Dokument richtig lesbar machen werde. Aufgrund verschiedener Untersuchungen schien ReDoc gut zu sein. Die API-Referenz für Docker Engine scheint dies ebenfalls zu verwenden.
Ändern Sie den JAX-RS-Pfad
Ich möchte HTML einfügen, aber da der Stammpfad standardmäßig der JAX-RS-Pfad ist, ändern Sie ihn in "/ api".
JaxRsActivator.java
// package,Import weggelassen
@ApplicationPath("api")
public class JaxRsActivator extends Application {
}
Dies ändert die Ressource "/ hello" in "/ api / hello".
Erstellen Sie HTML für ReDoc
Es ist auch in ReDoc README.md geschrieben, aber ich werde eine HTML-Datei wie folgt einfügen.
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>
<!--Hier/Ich werde mich auf openapi beziehen!-->
<redoc spec-url='/openapi'></redoc>
<script src="https://cdn.jsdelivr.net/npm/redoc@next/bundles/redoc.standalone.js"></script>
</body>
</html>
Wenn Sie es danach auf die gleiche Weise neu erstellen und starten 。 JAX-RS-Ressourcen finden Sie unter http: // localhost: 8080 / api / hello Sie können die OpenAPI Specification-konforme YAML unter http: // localhost: 8080 / openapi sehen Unter http: // localhost: 8080 / haben Sie ein cooles API-Dokument!
Wenn Sie verschiedene Informationen wie Titel, Lizenz, Kontaktinformationen usw. festlegen möchten. Src / main / resources / META-INF / openapi.json [Format gemäß OpenAPI-Spezifikation](https://github.com/OAI/ Wenn Sie es mit OpenAPI-Spezifikation / blob / master / version / 3.0.1.md # (Spezifikation) ändern, wird es auf der Seite angezeigt.
Weitere Verbesserung der Dokumentation
Das MicroProfile OpenAPI bietet verschiedene Anmerkungen. Wenn Sie es entsprechend an die JAX-RS-Ressource anhängen, können Sie Informationen hinzufügen, die der OpenAPI-Spezifikation entsprechen.
Wenn Sie außerdem Erweiterung entsprechend ReDoc, der API, festlegen Es scheint, dass Sie die Funktion zum Generieren von Beispielcode für den Client hinzufügen und Informationen wie das JSON-Beispiel zu "POST" hinzufügen können.
Code für Demo gemacht
Es ist auf GitHub https://github.com/sightseeker/wildfly-swarm-mp-demo veröffentlicht. Wenn Sie es also sofort ausprobieren möchten, klicken Sie bitte hier.
Files
Dies ist die einzige Datei.
├── pom.xml
└── src
└── main
├── java/com/sightseekerstudio/wildflyswarmmpdemo/rest
│ ├── HelloWorldEndpoint.java
│ └── JaxRsActivator.java
├── resources
│ └── META-INF
│ └── openapi.json
└── webapp
└── index.html
Recommended Posts