[17.0.0.1 以及更新版本]

改寫 Swagger 2.0 文件欄位

server.xml 檔中使用 swaggerDefinition 屬性,以改寫 Swagger 2.0 文件(由 /docs/explorer 端點提供)中的部分欄位。

開始之前

您必須先將 apiDiscovery-1.0 特性新增至 server.xml 檔,然後在 Liberty REST 端點中公開 Swagger 2.0 說明文件。 完成探索 Liberty 伺服器中的 REST API 說明文件中的程序步驟 1 和 2。

程序

  1. 建立 swaggerDefinition Snippet 來指定 JSON 或 YAML Swagger Snippet,其中包含要改寫的欄位。您可以改寫 infoschemesconsumesproducesexternalDocs 欄位。

    例如,下列 swaggerDefinition Snippet 會在 /explorer HTML 頁面中變更 descriptiontitle 及其他 info 欄位。

    {  
      "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"
         }
      }
    }

    除了 titledescription 值,您還可以自訂 /explorer HTML 頁面中的橫幅和標誌 HTML 元素。 在 swaggerDefinition Snippet 的 info 欄位內,您可以指定 x-ibm-css 欄位來指向 CSS 檔的位置,以置換橫幅和標誌部分。 此 CSS 檔有下列格式需求:

    • CSS 檔必須指定 .swagger-section #header CSS 元素。
    • 任何新的標誌必須使用 images/custom-logo.png 格式,其中 custom-logo 是影像檔的名稱。請將標誌檔路徑設為相對於 CSS 檔。
    • CSS 檔必須將 background-image 內容設為 url(images/custom-logo.png) 值,才能參照自訂標誌影像。
    • 標誌檔必須是 PNG 格式。

    置換 CSS 檔的範例如下:

    .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. swaggerDefinition 屬性新增至 server.xml 檔。

    swaggerDefinition 屬性值可以是下列其中一個值:

    • 本端檔案的路徑,結尾是 .json.yaml 副檔名。這個路徑可以包含與執行時期目錄相關聯的 Liberty 變數;例如:
      <apiDiscovery swaggerDefinition="${server.config.dir}/custom/swaggerDef.yaml" />
    • Swagger Snippet 的絕對 URL,開頭為 httphttps;例如:
      <apiDiscovery swaggerDefinition="http://mycompany.com/api/swaggerDef.json" />
    • 部署在伺服器上之應用程式的環境定義根目錄。環境定義根目錄的開頭為正斜線 (/);例如:
      <apiDiscovery swaggerDefinition="/myApplication" />

    為了加強 Liberty 伺服器(包含一個已部署的 Web 應用程式)的使用者體驗,Web 應用程式的 Swagger 文件會作為 swaggerDefinition Snippet。 即使 server.xml 中未定義 swaggerDefinition 屬性,/docs 端點所提供的 Swagger 文件中也會置換應用程式的所有欄位。 當伺服器上部署第二個 Web 應用程式時,受到單一應用程式最佳化所影響的所有欄位會回復為預設值。


指示主題類型的圖示 作業主題

檔名:twlp_api_discovery_swagger_def.html