[17.0.0.1 und höher]

Swagger 2.0-Dokumentfelder überschreiben

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

  1. 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;
    }
  2. 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.


Symbol das den Typ des Artikels anzeigt. Taskartikel

Dateiname: twlp_api_discovery_swagger_def.html