[17.0.0.3 以及更新版本]

自訂 OpenAPI 說明文件

您可以針對位於 /api/docs 端點的主要 OpenAPI 文件以及位於 /api/explorer 的 OpenAPI 使用者介面,使用 externalDocsinfo 等元素,來自訂其各個層面。Liberty 會監視位於預設路徑位置之自訂作業檔案的變更,來處理及更新主要 OpenAPI 文件和使用者介面的變更。

開始之前

如果要瞭解如何建置和啟用 OpenAPI 說明文件,請參閱使用 OpenAPI 來產生 REST API 說明文件

使用範例 OpenAPI 第 3 版 airlines 應用程式,來產生說明文件,並呈現可自訂的使用者介面範例。

程序

  1. 在 OpenAPI Snippet 中定義一項自訂作業。 建立一個遵循 OpenAPI 3.0.0 規格結構的 Snippet。此 Snippet 可以放在 YAML 或 JSON 檔案中,或從 URL 取得。

    info 元素提供標題、說明和其他資訊。您可以自訂標題和說明的值。您也可以自訂標頭列,以編輯標誌、過濾框和過濾按鈕。在自訂作業 Snippet 的 info 欄位內,針對設定了標頭列 HTML 元素樣式的 CSS 檔案,使用 x-ibm-css 欄位來指向該 CSS 檔的位置。

    Snippet 不需要獨立完成。下列的範例 Snippet 會自訂 info 元素,使其指向設定了 OpenAPI 使用者介面之標頭列樣式的 CSS。

    ---
    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

    CSS 可以是本端檔案或從 URL 取得。路徑可以包含執行時期目錄相關聯的 Liberty 變數。

    這個 CSS 檔案會將下列格式需求視為有效。
    • CSS 檔案指定了至少一個以 .swagger-ui .headerbar 開頭的元素。
    • 只會使用 CSS 元素之下所指定以 .swagger-ui .headerbar 開頭的內容。
    • CSS 檔案所參照之自訂標誌檔案必須是 PNG 格式。
    • 自訂標誌檔案必須命名為 custom-logo.png,並且放在 images/custom-logo.png 中。
    • 標誌檔案路徑必須相對於 CSS 檔案。
    • CSS 檔案必須將 background-image 內容設為 url(images/custom-logo.png) 值,以參照標誌影像。
    下列的範例 Snippet 顯示置換用的 CSS 檔案。
    .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;
    }
  2. 為自訂作業檔案配置檔案監視。

    您可以將自訂作業檔案儲存在預設位置,以進行自動監視,或者您可以變更伺服器配置,以定義您檔案的位置。如果指定了多個預設自訂作業檔案,您會看到一則送往主控台的警告訊息輸出,指出要監視的自訂作業檔案以及要忽略的檔案。選取要監視的自訂作業檔案會由 Liberty 持續監視,直到刪除它為止。

    註: 只會監視自訂作業檔案是否有更新。不會監視 CSS 和標誌檔案。不會監視 URL。
    1. 以 YAML、YML 或 JSON 檔案類型,將自訂作業 Snippet 儲存在 ${server.config.dir}/openapi/customization.file_type,以採用預設自訂作業檔案監視。
    2. 選擇性的: Liberty 伺服器配置檔中新增 openapi 元素,並為元素指定 customization 屬性,以參照該 Snippet。

      當明確設定 customization 屬性時,不會監視預設自訂作業定義位置。customization 屬性可以指定 YAML、YML 或 JSON 檔案,以交由 Liberty 監視。路徑可以包含執行時期目錄相關聯的 Liberty 變數,如下列範例所示。

      <openapi customization="${server.config.dir}/custom/customInfo.yaml" />

      customization 屬性也可以指定一個 URL,以傳回 OpenAPI Snippet。

      <openapi customization="http://myWebsite.com/myCustomOpenAPI" />
  3. 選擇性的: 停用自訂作業檔案的檔案監視。

    依預設,Liberty 會持續監視自訂作業檔案。不過,監視檔案時會使用額外的系統資源。如果您沒有任何自訂作業檔案,或者您的自訂作業檔案是靜態的且沒有變更,最好關閉檔案監視。

    在您的伺服器配置檔中,將 openapi 元素的 disableFileMonitor 布林屬性設為 true。當 disableFileMonitor 屬性設為 true 時,也不會監視預設自訂作業定義位置。
    <openapi disableFileMonitor="true" />

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

檔名:twlp_api_openapi_custom.html