Das Feature mpOpenAPI-1.0 stellt eine Implementierung der MicroProfile-OpenAPI-Spezifikation Version 1.0 und einen Satz von Java-Schnittstellen und Programmiermodellen, die es Java-Entwicklern ermöglichen, nativ OpenAPI-V3-Dokumente aus Ihrer JAX-RS-Anwendung zu erzeugen. Anschließend können Sie die mit dem Feature mpOpenAPI-1.0 generierte API-Dokumentation in einem Browser anzeigen, der eine benutzerfreundliche Benutzerschnittstelle verwendet.
Vorbereitende Schritte
Erfahren Sie
hier mehr über die OpenAPI-Spezifikation Version 3 und
hier zur MicroProfile-OpenAPI-1.0-Spezifikation. Sie können eine statische OpenAPI-Datei entweder im YAML- oder im JSON-Format verwenden, MicroProfile-OpenAPI-Annotationen oder OpenAPI-Programmiermodelle verwenden, um die REST-konformen APIs in Ihrer Anwendung zu dokumentieren.
Fehler vermeiden: - Erweiterungen und Erweiterungsannotationen werden nur auf Operations- und Klassenebene unterstützt. Verwenden Sie andere Dokumentationsmechanismen, um Erweiterungen für andere Elemente anzugeben.
- Wenn Sie beim ersten Mal falsche Berechtigungsnachweise eingeben, verhält sich die OpenAPI-Benutzerschnittstelle nicht wie erwartet. Wenn danach die richtigen Berechtigungsnachweise eingegeben werden, bleibt das Problem bestehen und Sie werden möglicherweise wiederholt zur Eingabe von Berechtigungsnachweisen aufgefordert. Aktualisieren Sie die Seite und geben Sie die richtigen Berechtigungsnachweise ein.
- Wenn Sie das Feature ssl-1.0 aktivieren, nachdem Sie das Feature mpOpenAPI-1.0 aktiviert haben, werden möglicherweise beim Zugriff auf die Endpunkte /openapi oder openapi/ui Ausnahmen ausgelöst. Wenn Sie diesesn Problem vermeiden möchten, aktivieren Sie beide Features zusammen. Um das Problem zu beheben, nachdem es aufgetreten ist, inaktivieren Sie das Feature mpOpenAPI-1.0 und aktivieren Sie es anschließend wieder.
Wenn mehrere Anwendungen implementiert werden, wird eine Anwendung zum Generieren der OpenAPI-Dokumentation ausgewählt. Es wird eine Informationsnachricht ausgegeben, um anzugeben, welche Anwendung ausgewählt wurde. Wenn die ausgewählte Anwendung aktiv ist, werden alle anderen Anwendungen vom Anwendungsprozessor ignoriert. Sobald die ausgewählte Anwendung gestoppt wurde, wird die nächste Anwendung verarbeitet.
Vorgehensweise
- Optional: Konfigurieren Sie verschiedene Teile der MicroProfile-OpenAPI-Spezifikation mithilfe des MicroProfile-Config-Mechanismus anhand der Anforderungen für Ihre Anwendung. Das Feature mpOpenAPI-1.0 liest die konfigurierten Werte, wenn Ihre Anwendung gestartet wird.
- Konfigurieren Sie eine oder mehrere der Basiskonfigurationen, die für Ihre Anwendung in der MicroProfile-OpenAPI-Spezifikation verfügbar sind.
- Das Feature mpOpenAPI-1.0 validiert als Mehrwertergänzung das finale OpenAPI-Dokument, das für die Anwendung generiert wird, anhand der Einschränkungen, die in der Spezifikation von OpenAPI Version 3.0 deklariert sind. Die Validierungsergebnisse, eine Kombination aus Fehlern und Warnungen, werden in das Konsolenprotokoll ausgegeben.
Die Validierung ist standardmäßig für Anwendungen aktiviert. Sie können die Validierung inaktivieren, indem Sie die folgende Konfiguration festlegen.
mp.openapi.extensions.liberty.validation=false
- Wählen Sie eine der folgenden Methoden oder eine Kombination aus den folgenden Methoden aus, um Eingaben für die Generierung resultierender OpenAPI-Dokumente gemäß der Beschreibung unter Dokumentationsmechanismen bereitzustellen.
- Verwenden Sie das Programmiermodell, um Bootstrapping oder die vollständige OpenAPI-Modellbaumstruktur bereitzustellen.
- Verwenden Sie einen Texteditor, um ein statitisches OpenAPI-Dokument im YAML- oder im JSON-Format zu schreiben und anschließend die Datei
openapi.yaml, openapi.yml oder openapi.json im Verzeichnis META-INF Ihrer Anwendung zu speichern.
- Geben Sie die MicroProfile OpenAPI-Annotationen im Java-Code an, um eine Anwendung zu erweitern und zu dokumentieren.
- Verwenden Sie Filter, um das OpenAPI-Modell zu aktualisieren, nachdem es unter Verwendung der Dokumentationsmechanismen erstellt wurde.
- Aktivieren Sie das Feature mpOpenAPI-1.0 in der Liberty-Serverkonfiguration.
<server>
<featureManager>
<feature>mpOpenAPI-1.0</feature>
</featureManager>
</server>
- Implementieren Sie Ihre Anwendung.
- Optional: Überprüfen Sie die Validierungsergebnisse und stellen Sie sicher, dass Ihre Anwendung mit der OpenAPI-Spezifikation Version 3.0 konform ist.
- Suchen Sie im Konsolenprotokoll nach Validierungsfehlern.
- Die Ereignisse werden in Fehler und Warnungen gruppiert. Die Nachricht enthält außerdem die zugehörige Position im generierten Dokument, damit Sie das zugehörige Element angeben können.
Beispiel für die Nachricht:
CWWKO1650E: Bei der Validierung des OpenAPI-Dokuments wurden die folgenden Fehler erzeugt:
- Nachricht: Das erforderliche Feld "scopes" fehlt oder es ist auf einen ungültigen Wert gesetzt. Position: #/components/securitySchemes/reviewoauth/flows/authorizationCode
- Zeigen Sie das generierte API-Dokument in einem Browser an. Sie finden das generierte API-Dokument am Endpunkt /openapi, indem Sie eine der folgenden URLs verwenden.
- Wenn Sie Ihr Dokument mit den öffentlichen APIs ohne SSL anzeigen möchten, verwenden Sie die folgende URL: http://Liberty_host:http_port/openapi.
- Wenn Sie Ihr Dokument mit den öffentlichen APIs mit SSL anzeigen möchten, verwenden Sie die folgende URL: https://Liberty_host:https_port/openapi.
Ergebnisse
Die OpenAPI-Benutzerschnittstelle gibt die Definition aus
/openapi wieder, um eine Benutzerschnittstelle unter
http://Liberty-Host:HTTP-Port/openapi/ui anzuzeigen. Wenn Sie SSL aktivieren, können Sie auf die geschützte Benutzerschnittstelle unter
https://Liberty-Host:HTTPS-Port/openapi/ui zugreifen.