聚集 REST API 說明文件

您可以使用支援 MicroProfile OpenAPI 規格的 openapi-3.1 特性，來聚集您所產生的 REST API 說明文件。 記載 REST API、指定公用和專用 API ，以及將 Web 應用程式部署至 Liberty 伺服器。 之後您就可以在使用人類可讀使用者介面的瀏覽器中，檢視 openapi-3.1 產生的 API 說明文件。

[21.0.0.12 以及更新版本]穩定特性: openapi-3.1 特性已穩定。 您可以繼續使用此特性。 不過，策略性替代方案是使用 MicroProfile OpenAPI 特性，例如 mpOpenAPI-3.0。

開始之前

openapi-3.1 特性是實作 MicroProfile OpenAPI 規格之 mpOpenAPI-1.0 特性的延伸。 如需 mpOpenAPI-1.0 特性的相關資訊，請參閱 使用 MicroProfile OpenAPI 1.0 產生 REST API 說明文件。

程序

  1. 建置 OpenAPI 說明文件。 請檢閱 使用 MicroProfile OpenAPI 產生 REST API 文件 ，以取得建置文件的程序。
  2. 在 Liberty 伺服器配置中啟用 openapi-3.1 特性。
    1. 將 openapi-3.1 特性新增至特性管理程式:
      <server>
   <featureManager>
      <feature>openapi-3.1</feature>
   </featureManager>
</server>
    2. 選用: 指定應用程式 OpenAPI 是專用的。 依預設，OpenAPI 說明文件是公用的。 所有使用者通常不需鑑別，就可以存取公用 API。 公用 API 記載於 /api/docs resource。 您可以指定 API 維持專用。 管理用的 API 通常維持專用。 使用密碼保護的專用 API 記載於 /ibm/api/docs 資源中。 這個資源記載了所有專用 API 和所有公用 API。 您可以為 Web 應用程式指定專用 API，作法是在應用程式層次設定 MicroProfile 配置內容 mp.openapi.extensions.liberty.public=false。 依預設，內容值是 true。 只有在您想停用要維持專用的應用程式時，才需要這項配置。
    3. 選用: 指定應用程式未出現在 OpenAPI 文件中。 依預設，包含 REST API 文件的 Web 模組會出現在 /api/docs 資源中可用的合併 OpenAPI 文件中。 如果要阻止 Web 模組出現在 OpenAPI 文件中，請設定下列 MicroProfile 配置內容的值：mp.openapi.extensions.liberty.exclude.context.roots。 這個內容的值是您想隱藏的環境定義根目錄清單，並以逗點區隔。 請識別您想藉由其環境定義根目錄來隱藏的每一個 Web 模組，並將那些環境定義根目錄新增至該內容的值中。 例如，如果要隱藏其環境定義根目錄為 /airlinesAdmin 的 Web 模組，您可以設定 mp.openapi.extensions.liberty.exclude.context.roots=/airlinesAdmin。 當啟用 openapi-3.1 特性時，會讀取這個內容。
  3. 部署應用程式。
  4. 視您的 API 是公用或專用而定，您可以使用下列其中一個 URL ，在 /api/docs 端點找到產生的 API 文件。
      • 對於非 SSL 公用 API，請檢視位於 http://Liberty_host:http_port/api/docs 的文件。
      • 對於 SSL 公用 API，請檢視位於 https://Liberty_host:https_port/api/docs 的文件。
      • 對於 SSL 專用 API，請檢視位於 https://Liberty_host:https_port/ibm/api/docs 的文件。
    提示：
    依預設，伺服器有下列兩個端點可用。
      • GET http://Liberty_host:http_port/api/docs
      • GET http://Liberty_host:http_port/api/explorer
    您可以使用下列 MicroProfile 配置內容，來自訂公用端點的 URL：mp.openapi.extensions.liberty.public.url。 啟用 openapi-3.1 特性時，會讀取這個內容。 下列範例說明 MicroProfile 配置，以透過 GET http://Liberty_host:http_port/myAPI/docs 和 http://Liberty_host:http_port/myAPI/explorer，提供公用 REST API 說明文件。
    mp.openapi.extensions.liberty.public.url=myAPI

    OpenAPI 文件在該 Liberty 伺服器的應用程式之間產生並聚集。 依預設，文件是 YAML 格式。 如果 HTTP 要求中的 Accept 標頭值是 application/json，則文件是 JSON 格式。 或者，也可以使用格式查詢參數: http://Liberty_host:http_port/api/docs?format=json

    提示：

    您可以依環境定義根目錄來過濾 OpenAPI 說明文件。 公用端點 (api/docs) 和專用端點 (ibm/api/docs) 都支援 root 查詢參數，此參數可過濾找到的環境定義根目錄。 例如，呼叫

    GET http://Liberty_host:http_port/api/docs?root=/myApp 擷取僅具有 myApp 環境定義根目錄文件的 OpenAPI V3 文件。

結果

OpenAPI 使用者介面會從 http://Liberty_host:http_port/api/explorer中的 /api/docs 呈現聚集定義。 如果您啟用 SSL ，則可以在 https://Liberty_host:https_port/api/explorer存取受保護的使用者介面。

您可以設定 MicroProfile 配置內容 mp.openapi.extensions.liberty.enable.private.url=true，來瀏覽專用 Web 模組。 當啟用 openapi-3.1 特性時，會讀取這個內容。

當啟用專用 Web 模組瀏覽時，請使用 https://Liberty_host:https_port/ibm/api/explorer 來顯示公用和專用 Web 模組的友善使用者介面。

您可以在這個使用者介面中，檢視您應用程式中所有的 RESTful 端點。 您也可以過濾顯示的端點，以聚焦在特定的應用程式。