Verwenden Sie ein swaggerDefinition-Attribut in einer Datei server.xml, um einige Felder in den Swagger 2.0-Dokumenten zu überschreiben, die von den /docs- und /explorer-Endpunkten bereitgestellt werden.
Vorbereitende Schritte
Sie müssen zuerst das Feature apiDiscovery-1.0 Ihrer Datei server.xml hinzufügen und anschließend die Swagger 2.0-Dokumentation in
den Liberty-REST-Endpunkten zur Verfügung stellen. Führen Sie die Schritte 1 und 2 der Prozedur in REST-API-Dokumentation auf einem Liberty-Server suchen aus.
Vorgehensweise
- Erstellen Sie ein swaggerDefinition-Snippet, um ein JSON- oder YAML-Swagger-Snippet anzugeben, das zu überschreibende Felder enthält. Sie können die Felder info, schemes, consumes, produces und externalDocs überschreiben.
Das folgende swaggerDefinition-Snippet ändert die Felder description, title und weitere info-Felder in den /explorer-HTML-Seiten.
{
"swagger" : "2.0",
"info":{
"description":"My description",
"version":"1.0.0",
"title":"My title",
"x-ibm-css":"${server.config.dir}/css/acme-banner.css",
"termsOfService":"http://swagger.io/terms/",
"contact":{
"email":"apiteam@swagger.io"
},
"license":{
"name":"Apache 2.0",
"url":"http://www.apache.org/licenses/LICENSE-2.0.html"
}
}
}
Zusätzlich zu den title- und den description-Werten können Sie das Banner und die HTML-Elemente für das
Logo der /explorer-HTML-Seiten anpassen. Im info-Feld des swaggerDefinition-Snippets können Sie ein
x-ibm-css-Feld angeben, um auf eine Position einer CSS-Datei zu verweisen, die das Banner und den Logoabschnitt überschreibt. Diese CSS-Datei hat die folgenden Formatanforderungen:
- Die CSS-Datei muss ein CSS-Element des Typs .swagger-section #header angeben.
- Alle neuen Logos müssen das Format images/custom-logo.png haben. Hierbei steht custom-logo für den Namen der Bilddatei. Geben Sie den Logodateipfad relativ zur CSS-Datei an.
- Die CSS-Datei muss das angepasste Logobild referenzieren. Hierfür muss die Eigenschaft background-image auf den Wert url(images/custom-logo.png) gesetzt werden.
- Die Logodatei muss das PNG-Format haben.
Im Folgenden sehen Sie ein Beispiel für überschreibende CSS-Datei:
.swagger-section #header {
background-image: url(images/custom-logo.png);
background-repeat: no-repeat;
background-color: lightslategray;
background-position-x: 28px;
padding-top: 20px;
padding-right: 0px;
padding-bottom: 20px;
padding-left: 5px;
height: 75px;
}
- Fügen Sie Ihrer Datei server.xml ein swaggerDefinition-Attribut hinzu.
Das swaggerDefinition-Attribut kann einen der folgenden Werte haben:
- Pfad einer lokalen Datei, die mit der Dateierweiterung .json oder .yaml endet. Dieser Pfad kann Liberty-Variablen enthalten, die Laufzeitverzeichnissen zugeordnet sind, z. B.:
<apiDiscovery swaggerDefinition="${server.config.dir}/custom/swaggerDef.yaml" />
- Die absolute URL eines Swagger-Snippets, das mit http oder https beginnt, z. B.:
<apiDiscovery swaggerDefinition="http://mycompany.com/api/swaggerDef.json" />
- Kontextstammverzeichnis einer Anwendung, die im Server implementiert ist. Das Kontextstammverzeichnis beginnt mit einem Schrägstrich (/), z. B.:
<apiDiscovery swaggerDefinition="/myApplication" />
Zur Verbesserung der Attraktivität für den Benutzer eines Liberty-Servers mit einer implementierten Webanwendung wird das Swagger-Dokument der Webanwendung als swaggerDefinition-Snippet verwendet. Alle Felder aus der Anwendung werden in einem Swagger-Dokument überschrieben, das über die /docs-Endpunkte bereitgestellt wird, obwohl kein swaggerDefinition-Attribut in der Datei server.xml definiert wurde. Wenn eine zweite Webanwendung in einem Server implementiert wird, werden alle Felder, die von der Einzelanwendungsoptimierung betroffen sind, auf die zugehörigen Standardwerte zurückgesetzt.