以 MicroProfile OpenAPI 產生 REST API 說明文件

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

Open Liberty 如需使用 Liberty MicroProfile OpenAPI 特性 1.0 版以及更新版本的相關資訊，請參閱 Open Liberty 網站

開始之前

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

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

程序

  1. 選用: 視您應用程式的需要，透過 MicroProfile config 機制，來配置 MicroProfile OpenAPI 規格的各種組件。
    當啟動應用程式時，mpOpenAPI-1.1 特性會讀取所配置的值。
    • 針對您的應用程式，配置 MicroProfile OpenAPI 規格中提供的一或多個 核心配置 。
    • 如果要新增值，mpOpenAPI-1.1 特性會驗證產生給應用程式的最終 OpenAPI 文件，看看是否符合「OpenAPI 規格 3.0 版」中所宣告的各項限制。 驗證結果（錯誤和警告的組合）會輸出至主控台日誌。
      依預設，會為應用程式啟用驗證。 您可以設定下列配置，來停用驗證。
      mp.openapi.extensions.liberty.validation=false
  2. 選擇下列其中一種或組合來提供輸入，以便依照 說明文件機制中的說明來產生所產生的 OpenAPI 文件。
    • 使用 程式設計模型 來提供引導或完整 OpenAPI 模型樹狀結構。
    • 使用文字編輯器以 YAML 或 JSON 格式撰寫 靜態 OpenAPI 文件 ，然後將 openapi.yaml、 openapi.yml或 openapi.json 檔案放置在應用程式的 META-INF 目錄中。
    • 在 Java 程式碼中指定 MicroProfile OpenAPI 註釋 ，以擴增及記載應用程式。
    • 在使用文件機制建置 OpenAPI 模型之後，請使用 filter 來更新它。
  3. 在 Liberty 伺服器配置中啟用 mpOpenAPI-1.1 特性。
    <server>
   <featureManager>
      <feature>mpOpenAPI-1.1</feature>
   </featureManager>
</server>
  4. 部署應用程式。
  5. 選用項目: 請檢查驗證結果，並確定您的應用程式符合 OpenAPI Specification 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 存取受保護的使用者介面。