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

您可以使用「API 探索」特性,來探索 Liberty 伺服器上的 REST API 說明文件,以尋找可用的 REST API。請使用 Swagger 使用者介面,來啟動可用的 REST 端點。
[18.0.0.1 以及更新版本]提示: 您可以使用 openapi-3.0 特性,來探索 REST API 說明文件。openapi-3.0 特性可分類成下一版 apiDiscovery-1.0 特性。您可以將使用 apiDiscovery-1.0 建立的 Swagger 第 2 版文件更新為 OpenAPI 第 3 版。請參閱 使用 OpenAPI 來產生 REST API 說明文件

程序

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

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

    請確定伺服器配置具有您所部署之應用程式所需的所有特性,例如 jaxrs-2.0。修改埠,使伺服器可以開啟它的 HTTP 埠。

    如果您要顯示專用 REST API 說明文件,請在 server.xml 檔中配置金鑰儲存庫服務物件登錄及使用者登錄設定。

    [17.0.0.1 以及更新版本]不過,如果您只想顯示公用 REST API 說明文件,則只有當您想要透過 HTTPS 存取文件時,才需要新增金鑰儲存庫物件登錄。 透過 HTTP 存取公用說明文件時,不需要金鑰儲存庫物件登錄,也不需要使用者登錄設定。

    下列 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-mapping

    啟用 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.1</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,而且可能還可以從頁面來啟動它們。

      頁面上的過濾器輸入框容許使用以逗點區隔的環境定義根目錄清單,來過濾內容。

    • [17.0.0.1 以及更新版本]使用其他端點來顯示公用 REST 說明文件。

      與先前提及的端點不同,存取這些端點時不需要金鑰儲存庫服務物件登錄,也不需要使用者登錄設定。 不過,您可以設定金鑰儲存庫服務物件登錄,以透過 HTTPS 來存取端點。

      依預設,伺服器有下列兩個端點可用:
      • GET http://host:http_port/api/docs
      • GET http://host:http_port/api/explorer

      您可以使用 server.xml 中的 publicURL 屬性,以變更公用端點的 URL。 例如,在 server.xml 中設定下列配置,就可透過 GET http://host:http_port/myAPI/docshttp://host:http_port/myAPI/explorer 提供公用 REST API 說明文件:

      <apiDiscovery publicURL="myAPI" />

      依預設,已部署的 Web 應用程式所提供的所有 REST API 端點(內部伺服器端點除外,例如 JMX REST 連接器 REST API),都會顯示在公用 REST API 說明文件中。 您可以設定 public="false" 屬性,讓 Web 模組不顯示模組所顯示的 REST API。例如,將下列配置新增至 server.xml 時,Web 模組的 REST API 就不會顯示在公用 REST API 說明文件中:

      <apiDiscovery publicURL="myAPI">
         <webModuleDoc contextRoot="/22ExampleServlet" public="false" />
      </apiDiscovery>
    • [17.0.0.1 以及更新版本]server.xml 檔中使用 swaggerDefinition 屬性,以改寫 Swagger 2.0 文件(由 /docs 端點提供)中的部分欄位

      您可以使用 swaggerDefinition 指定 JSON 或 YAML Swagger Snippet,其中包含要改寫的欄位。您可以改寫 infoschemesconsumesproducesexternalDocs 欄位。

    啟用 apiDiscovery-1.0 特性之後,ObjectName 值為 WebSphere:feature=apiDiscovery,name=APIDiscovery 的管理 Bean (MBean) 已在 LibertyMBeanServer 中進行登錄。 這個 MBean 提供下列屬性:

    • DocumentationURL 屬性是 /ibm/api/docs 端點的完整 URL,它會顯示原始 JSON 或 YAML 說明文件。
    • ExplorerURL 屬性是 /ibm/api/explorer 端點的完整 URL,它會顯示此說明文件呈現的使用者介面。

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

範例

您可以在 OpenAPI 介面WASdev 網站上找到「REST API 探索」的相關資訊。

用聲音簡報的 IBM MediaCenter Flash 視訊 觀看:IBM MediaCenter 上的 IBM WebSphere Application Server Liberty API 探索視訊提供範例以及示範視訊的鏈結。(8.5.5.9 版)


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

檔名:twlp_api_discovery.html