Sie können Teile des verfügbaren OpenAPI-Masterdokuments, das am Endpunkt /api/docs verfügbar ist, und der OpenAPI-Benutzerschnittstelle, die unter /api/explorer verfügbar ist, mit Elementen, wie z. B. dem Element externalDocs und dem Element info anpassen. Liberty überwacht Änderungen an den Anpassungsdateien an den Standardpfadpositionen, um Änderungen am OpenAPI-Masterdokument und der Benutzerschnittstelle zu verarbeiten und zu aktualisieren.
Vorgehensweise
- Definieren Sie eine Anpassung ein einem OpenAPI-Snippet. Erstellen Sie ein Snippet, das der Struktur der Spezifikation von OpenAPI 3.0.0 folgt. Das Snippet kann eine YAML- oder JSON-Datei oder über eine URL verfügbar sein.
Das Element info stellt Titel, Beschreibung und weitere Informationen bereit. Sie können die Werte für Titel und Beschreibung anpassen. Sie können außerdem die Titelleiste anpassen, um das Logo, das Filterfeld und die Schaltfläche zum Filtern zu bearbeiten. Verwenden Sie im info-Feld des Anpassungssnippets ein x-ibm-css-Feld, um auf die Position einer CSS-Datei zu verweisen, die für die Darstellung von HTML-Elementen in der Titelleiste verantwortlich ist.
Das Snippet muss nicht in sich abgeschlossen sein. Das folgende Beispielsnippet passt das info-Element an, das auf eine CSS-Datei verweist, die für die Darstellung der Titelleiste in der OpenAPI-Benutzerschnittstelle verantwortlich ist.
---
openapi: 3.0.0
info:
title: Airlines APIs
description: Book flights and manage reservations
version: 2.1.0
x-ibm-css: ${server.config.dir}/openapi/header.css
Die CSS-Datei kann eine lokale Datei oder über eine URL verfügbar sein. Der Pfad kann Liberty-Variablen enthalten, die den Laufzeitverzeichnissen zugeordnet sind.
Diese CSS-Datei hat die folgenden Formatanforderungen, damit sie gültig ist.
- Die CSS-Datei gibt mindestens ein Element an, das mit .swagger-ui .headerbar beginnt.
- Es werden nur die Inhalte verwendet, die für die CSS-Elemente angegeben sind, die mit .swagger-ui .headerbar beginnen.
- Die angepasste Logodatei, die von der CSS-Datei referenziert wird, muss im PNG-Format sein.
- Eine angepasste Logodatei muss den Namen custom-logo.png haben und im Verzeichnis images/custom-logo.png gespeichert werden.
- Der Pfad der Logodatei muss relativ zur CSS-Datei sein.
- Die CSS-Datei muss das Logobild mit der Eigenschaft background-image referenzieren, deren Wert auf url(images/custom-logo.png) gesetzt ist.
Das folgende Beispielsnippet zeigt eine überschreibende CSS-Datei.
.swagger-ui .headerbar {
background-color: #5f3345;
}
.swagger-ui .headerbar .headerbar-wrapper {
background-image: url(images/custom-logo.png);
}
.swagger-ui .headerbar .filter-wrapper .filter-button {
background: rgba(252, 48, 81, 0.53);
color: #e8e8e8;
}
.swagger-ui .headerbar .filter-wrapper input[type=text] {
border: 1px solid #ebebeb;
}
- Konfigurieren Sie die Dateiüberwachung für Ihre Anpassungsdateien.
Sie können Ihre Anpassungsdateien an der Standardposition für die automatische Überwachung speichern oder Sie ändern die Serverkonfiguration, um eine Position für Ihre Datei zu definieren. Wenn mehrere Anpassungsdateien angegeben werden, wird eine Warnung an der Konsole ausgegeben, in der die überwachte Anpassungsdatei und die Dateien angegeben werden, die ignoriert werden. Die für die Überwachung ausgewählte Anpassungsdatei wird fortlaufend von Liberty überwacht, bis sie gelöscht wird.
Anmerkung: Nur Anpassungsdateien werden auf Aktualisierungen überwacht. Die CSS- und die Logodateien werden nicht überwacht. URLs werden nicht überwacht.
- Speichern Sie das Anpassungssnippet in einer Datei des Typs YAML, YML oder JSON unter ${server.config.dir}/openapi/customization.Dateityp, um die Standardanpassungsdateiüberwachung zu verwenden.
- Optional: Fügen Sie ein openapi-element mit einem Attribut customization hinzu, das das Snippet in der
Liberty-Serverkonfigurationsdatei referenziert.
Standardpositionen für Anpassungsdefinitionen werden nicht überwacht, wenn das Attribut customization explizit gesetzt ist. Das Attribut
customization kann eine YAML-, YML- oder JSON-Datei angeben, die von Liberty überwacht wird. Der Pfad kann die Liberty-Variablen enthalten, die den Laufzeitverzeichnissen wie im folgenden Beispiel zugeordnet sind.
<openapi customization="${server.config.dir}/custom/customInfo.yaml" />
Das Attribut customization kann auch eine URL angeben, die ein OpenAPI-Snippet zurückgibt.
<openapi customization="http://myWebsite.com/myCustomOpenAPI" />
- Optional: Inaktivieren Sie die Dateiüberwachung für die Anpassungsdateien.
Liberty überwacht standardmäßig fortlaufend die Anpassungsdateien. Die Überwachung der Dateien benötigt jedoch zusätzliche Systemressourcen. Wenn Sie keine Anpassungsdateien haben oder Ihre Anpassungsdateien statisch sind und sich nicht ändern, sollten Sie daher die Dateiüberwachung inaktivieren.
Setzen Sie in Ihrer Serverkonfigurationsdatei das boolesche Attribut disableFileMonitor für das openapi-Element auf true. Standardpositionen für Anpassungsdefinitionen werden ebenfalls nicht überwacht, wenn das Attribut disableFileMonitor auf true gesetzt ist. <openapi disableFileMonitor="true" />