[18.0.0.1 以及更新版本]

以 MicroProfile OpenAPI 1.0 產生 REST API 說明文件

mpOpenAPI-1.0 特性提供 MicroProfile OpenAPI 規格 1.0 版的實作以及一組 Java 介面和程式設計模型,可讓 Java 開發人員從其 JAX-RS 應用程式,以原本方式產生 OpenAPI 第 3 版文件。之後,您可以在使用人類可讀之使用者介面的瀏覽器中,檢視以 mpOpenAPI-1.0 特性產生的 API 說明文件。

開始之前

瞭解 OpenAPI 第 3 版規格MicroProfile OpenAPI 1.0 規格。您可以使用 YAML 格式或 JSON 格式的靜態 OpenAPI 檔案、MicroProfile OpenAPI 註釋或 OpenAPI 程式設計模型,來記載您應用程式中的 RESTful API。
避免困難:
  • 只有作業層次和類別層次支援延伸和延伸註釋。對於其他元素,請使用其他說明文件機制來指定延伸。
  • 如果您第一次輸入的授權認證不正確,則 OpenAPI 使用者介面的行為將不符合預期。如果您之後輸入正確的認證,則問題仍在,且可能反覆地提示您提供認證。請重新整理頁面,並輸入正確的認證。
  • 如果在啟用 mpOpenAPI-1.0 之後,啟用 ssl-1.0 特性,當您存取 /openapiopenapi/ui 端點時,可能會導致異常狀況。如果要避免發生問題,請一起啟用這兩項特性。在問題發生之後,如果要解決,請停用再啟用 mpOpenAPI-1.0 特性。

如果部署了多個應用程式,則會選取其中一個應用程式來產生 OpenAPI 說明文件。會輸出參考訊息,以識別所選取的應用程式。如果選取的應用程式正在執行,應用程式處理器會忽略其他所有的應用程式。當選取的應用程式停止之後,會處理下一個應用程式。

程序

  1. 選擇性的: 如果您應用程式需要,請透過 MicroProfile 配置機制,來配置 MicroProfile OpenAPI 規格中的不同部分。 當啟動應用程式時,mpOpenAPI-1.0 特性會讀取所配置的值。
    • 為您的應用程式,配置 MicroProfile OpenAPI 規格所提供的一或多項核心配置
    • 如果要新增值,mpOpenAPI-1.0 特性會驗證產生給應用程式的最終 OpenAPI 文件,看看是否符合「OpenAPI 規格 3.0 版」中所宣告的各項限制。驗證結果(錯誤和警告的組合)會輸出至主控台日誌。
      依預設,會為應用程式啟用驗證。您可以設定下列配置,來停用驗證。
      mp.openapi.extensions.liberty.validation=false
  2. 選擇下列一或多種方法來提供輸入,以便依照 說明文件機制中的說明,來產生最終得出的 OpenAPI 文件。
    • 使用程式設計模型,提供一個引導或完整的 OpenAPI 模型樹狀結構。
    • 使用文字編輯器,來撰寫 YAML 或 JSON 格式的 靜態 OpenAPI 文件,然後將 openapi.yamlopenapi.ymlopenapi.json 檔放在您應用程式的 META-INF 目錄中。
    • 在 Java 程式碼中指定 MicroProfile OpenAPI 註釋,以擴增和記載應用程式。
    • 使用過濾器,以便在使用說明文件機制來建置 OpenAPI 模型之後加以更新。
  3. 在 Liberty 伺服器配置中,啟用 mpOpenAPI-1.0 特性。
    <server>
       <featureManager>
          <feature>mpOpenAPI-1.0</feature>
       </featureManager>
    </server>
  4. 部署應用程式。
  5. 選擇性的: 檢查驗證結果,並確定您的應用程式符合 OpenAPI 規格 3.0 版。
    • 檢查主控台日誌中是否有驗證錯誤。
    • 事件會分組成錯誤和警告。訊息還包含所產生之文件中的對應位置,以利您識別相關的元素。
      範例訊息:
      CWWKO1650E: Validation of the OpenAPI document produced the following error(s):
           
       - Message: Required "scopes" field is missing or is set to an invalid value, Location: #/components/securitySchemes/reviewoauth/flows/authorizationCode
  6. 在瀏覽器中檢視產生的 API 文件。 您可以使用下列其中一個 URL,來尋找在 /openapi 端點產生的 API 文件。
    • 對於非 SSL 公用 API,請檢視位於 http://Liberty_host:http_port/openapi 的文件。
    • 對於 SSL 公用 API,請檢視位於 https://Liberty_host:https_port/openapi 的文件。

結果

OpenAPI 使用者介面會呈現 /openapi 中的定義,以顯示位於 http://Liberty_host:http_port/openapi/ui 的使用者介面。如果您啟用 SSL,可在 https://Liberty_host:https_port/openapi/ui 存取受保護的使用者介面。

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

檔名:twlp_mpopenapi.html