探索 Liberty 伺服器中的 REST API 文件

您可以使用「API 探索」特性,來探索 Liberty 伺服器上的 REST API 說明文件,以尋找可用的 REST API。請使用 Swagger 使用者介面,來呼叫可用的 REST 端點。

程序

  1. 在您想尋找其可用 REST API 的 Liberty 伺服器的 server.xml 檔中,將 apiDiscovery-1.0 特性新增至特性管理程式。

    apiDiscovery-1.0 特性會在產品中啟用 REST API 探索軟體組。如果伺服器配置使用 restConnector-1.0 特性,此特性也會顯露 Liberty REST 端點(例如 JMX)的說明文件,如果伺服器配置使用 collectiveController-1.0 特性,則會顯露群體的說明文件。

    請確定伺服器配置具有您所部署之應用程式所需的所有特性,例如 servlet-3.0jsp-2.2 等。此外,請確定所部署應用程式的埠與使用者登錄設定正確。

    下列 server.xml 檔具有 apiDiscovery-1.0 特性:

    <server>
        <featureManager>
            <feature>apiDiscovery-1.0</feature>
        </featureManager>
    
        <httpEndpoint id="defaultHttpEndpoint"
                      host="*"
                      httpPort="8010"
                      httpsPort="8020"/>
    
        <keyStore id="defaultKeyStore" password="Liberty"/>
      
        <basicRegistry id="basic" realm="ibm/api">
            <user name="bob" password="bobpwd" />
        </basicRegistry>
    </server>
  2. 在 Liberty REST 端點中顯露 Swagger 2.0 說明文件。

    如果 Web 應用程式包含二或多個 javax.ws.rs.core.Application 類別實例,以便正確地與「API 探索」特性搭配運作,每一個應用程式都需要在 web.xml 檔中定義唯一的 javax.ws.rs.@ApplicationPath 值或 URL 對映。

    啟用 apiDiscovery-1.0 特性,將現行說明文件與它在註釋掃描期間找到的說明文件合併。 產品會在 Web 模組中搜尋 META-INF/stub/swagger.jsonMETA-INF/stub/swagger.yaml 檔。 如果這個特性找到其中任何一個檔案,它會產生一份 Swagger 文件,其中含有檔案內容以及在 Web 模組中的任何 JAX-RS 和 Swagger 註釋。 您可以利用這個特性來建立非 JAX-RS Servlet 的文件,因為文件會與 JAX-RS 部分自動合併起來。 您可以採下列兩種方式之一來配置您 API 說明文件的位置:

    • 使用 SPI com.ibm.wsspi.rest.api.discovery.APIProvider 介面的 getDocument 方法。

      getDocument 方法可讓延伸特性中的 OSGi 軟體組提供 REST API 文件給整體的主要說明文件。就本版來說,支援的 DocType 只有 DocType.Swagger_20_JSONDocType.Swagger_20_YAML。 這個介面的實作者可能在 java.lang.String 值中傳回序列化的 JSON 或 YAML 文件,或者,它們也可能傳入指向 JSON 或 YAML 檔案位置的檔案參照(字首是file:///)。

    • 使用已部署的 Web 應用程式。

      每一個 Web 模組都可以提供其自己的 REST API 文件。企業應用程式 (EAR) 檔案內可以有多個 WAR 檔具有不同的 Swagger 2.0 文件。

      顯露 Web 模組說明文件最簡單的作法,是在對應 META-INF 資料夾內包含 swagger.jsonswagger.yaml 檔。 在應用程式部署期間,「API 探索」特性會尋找每一個 Web 模組的 META-INF/swagger.json 值。如果找不到 META-INF/swagger.json 值,「API 探索」特性會尋找 META‐INF/swagger.yaml 值。

      顯露 Web 模組 REST API 文件的另一種作法是在 server.xml 配置檔中。請在母項 apiDiscovery 元素中,放置每一個 Web 模組的 webModuleDoc 元素;例如:

      <apiDiscovery>
         <webModuleDoc contextRoot="/30ExampleServletInEar" enabled="true" docURL="/swagger.json" />	
         <webModuleDoc contextRoot="/22ExampleServlet" enabled="false" />
         <webModuleDoc contextRoot="/custom" enabled="true" docURL="http://petstore.swagger.io/v2/swagger.json" />
      </apiDiscovery>

      webModuleDoc 元素必須有 contextRoot 屬性,以用來唯一識別您想顯露其說明文件的 Web 模組。

      enabled 選用屬性用來切換 Web 模組的 API 探索。這個屬性的預設值為 true

      docURL 屬性用來指定何處可找到 Web 模組的說明文件。docURL 值的開頭可以是正斜線 (/),這樣的 URL 是環境定義根目錄的相對 URL;例如 /30ExampleServletInEar/swagger.json。或者,如果是會識別說明文件完整位置的絕對 URL,則 docURL 值的開頭可以是 httphttps

      如果 Web 應用程式沒有提供 swagger.jsonswagger.yaml 檔,且應用程式含有 JAX-RS 標註的資源,您可以自動產生 Swagger 文件。 伺服器配置必須有 apiDiscovery-1.0 特性,以及 jaxrs-1.1jaxrs-2.0 特性;例如:
      <featureManager>
          <feature>apiDiscovery-1.0</feature>
          <feature>jaxrs-1.0</feature>
      </featureManager>
      產品會掃描 Web 應用程式中的所有類別來尋找 JAX-RS 和 Swagger 註釋,這會搜尋具有 @Path@Api@SwaggerDefinition 註釋的類別。 在 Web 應用程式部署或啟動期間,產品也會自動產生對應的 Swagger 文件。

      您也可以利用 apiDiscovery-1.0 特性,將先前產生的文件與它在註釋掃描期間找到的文件合併起來。 產品會在 Web 模組中搜尋 META-INF/stub/swagger.jsonMETA-INF/stub/swagger.yaml 檔。 如果這個特性找到其中任何一個檔案,它會產生一份 Swagger 文件,其中含有檔案的內容以及在 Web 模組中的任何 JAX-RS 和 Swagger 註釋。 您可以利用這個特性來建立非 JAX-RS Servlet 的文件,因為文件會與 JAX-RS 部分自動合併起來。

      此技術也可以用來略過註釋限制,例如:顯露安全定義。舉例來說,下列 swagger.json(在 META-INF/stub 內)可讓註釋參照這些定義:

      {
        "swagger" : "2.0",
        "securityDefinitions" : {
          "petstore_auth" : {
            "type" : "oauth2",
            "authorizationUrl" : "http://petstore.swagger.io/api/oauth/dialog,"
            "flow" : "implicit",
            "scopes" : {
              "write_pets" : "modify pets in your account",
              "read_pets" : "read your pets"
            }
          },
          "api_key" : {
            "type" : "apiKey",
            "name" : "api_key",
            "in" : "header"
          }
        }
      }
  3. 探索您的 API 文件。

    配置 API 文件的位置之後,其探索方式如下:

    • 使用 GET https://host:https_port/ibm/api/docs 端點。

      這個端點提供有效的 Swagger 2.0 文件,內含合併成單一文件的所有可用 Liberty REST API。如果消費者應用程式想以程式設計方式來導覽一組可用的 API(例如:「API 管理」解決方案),這樣做就很有用。併入一個含有 application/yaml 值的選用標頭 Accept,會以 YAML 格式來提供 Swagger 2.0 文件。 這個端點具有一個多基數的選用查詢參數,稱為 root,可用來過濾找到的環境定義根目錄。例如,呼叫 GET https://host:https_port/ibm/api/docs?root=/myApp,則會擷取只具有 myApp 環境定義根目錄說明文件的 Swagger 2.0 文件。

    • 使用 GET https://host:https_port/ibm/api/explorer 端點。

      此端點可呈現引人注意的 HTML 頁面,其中顯示來自 /ibm/api/docs URL 的內容。此頁面遵循標準線上範例 (http://petstore.swagger.io/) 的相同型樣,因此使用者可以呼叫 REST API。此端點可協助您探索 Liberty 伺服器上的可用 REST API,而且可能還可以從頁面來呼叫它們。頁面上的過濾器輸入框容許使用以逗點區隔的環境定義根目錄清單,來過濾內容。這項過濾的作法如同 root 查詢參數。您可以提供必要的輸入值,然後按一下試用一下,來試用這些 API。

    • 對於群體控制器,請使用 GET https://host:https_port/ibm/api/collective/explorer 端點。

      群體控制器上的這個端點可呈現引人注意的 HTML 頁面,其中顯示來自 /ibm/api/collective/docs URL 的內容。此端點可協助您探索整個群體上的可用 REST API,而且可能還可以從頁面來呼叫它們。頁面上的過濾器輸入框容許使用以逗點區隔的環境定義根目錄清單和伺服器 ID,來過濾內容。伺服器 ID 的格式是 "hostName,userDir,serverName"。伺服器 ID 必須用引號 (") 括住。 如果您想利用試用一下按鈕來試用這些 API,您需要在成員伺服器的 server.xml 中設定「跨來源要求共用 (CORS)」。

      例如,在成員伺服器的 server.xml 中,需要下列 Snippet 來提供 API /IBMJMXConnectorREST/mbeanCount

      <cors domain="/IBMJMXConnectorREST/mbeanCount"
                allowedOrigins="https://<controller_hostname>:<https_port>"
                allowedMethods="GET,POST,DELETE,PUT,PATCH,OPTIONS"
      		  allowedHeaders="Content-Type,api_key,Authorization"
      		  allowCredentials="true"
              />

      如需關於設定 CORS 的進一步資訊,請參閱在 Liberty 伺服器上配置「跨來源要求共用」

      註: CORS 需求只適用於 Swagger 使用者介面的群體版本 (https://host:https_port/ibm/api/collective/explorer)。
    啟用 apiDiscovery-1.0 特性之後,ObjectName 值為 WebSphere:feature=apiDiscovery,name=APIDiscovery 的管理 Bean (MBean) 已在 Liberty MBeanServer 中進行登錄。 這個 MBean 提供下列屬性:
    • DocumentationURL 屬性是 /ibm/api/docs 端點的完整 URL,它會顯示原始 JSON 或 YAML 說明文件。
    • ExplorerURL 屬性是 /ibm/api/explorer 端點的完整 URL,它會顯示此說明文件呈現的使用者介面。

    您可以利用這個 MBean 來瞭解是否啟用「REST API 探索」,以及用戶端在哪裡能呼叫到它。


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



「時間戳記」圖示 前次更新: 2016 年 11 月 30 日
http://www14.software.ibm.com/webapp/wsbroker/redirect?version=cord&product=was-libcore-mp&topic=twlp_api_discovery
檔名:twlp_api_discovery.html