從 Java 原始碼自動生成準確的 OpenAPI 描述

核心概念

本文提出了一種名為 AutoOAS 的新方法，可以直接從 Java 原始碼自動生成準確且詳細的 OpenAPI 描述，解決了現有方法的不足，並在真實世界專案中展現出更高的準確性和完整性。

摘要

這篇研究論文探討了從 Java 原始碼自動生成 OpenAPI 描述的議題，特別是針對 Spring Boot 專案。OpenAPI 描述對於 REST API 文件和使用至關重要，但手動創建既耗時又容易出錯。
現有方法的不足
作者首先評估了三種現有的 OpenAPI 生成方法：Respector、Prophet 和 springdoc-openapi。他們發現這些方法存在一些缺陷，包括：

忽略 Spring 設定檔：無法處理基於設定檔的不同 API 行為。
參數和回應處理不完整：無法正確處理模型屬性註解、JSON 屬性註解、請求主體註解和異常處理機制。
資料模型表示不佳：無法準確描述資料模型，特別是繼承資訊。
AutoOAS 方法
為了克服這些限制，作者提出了 AutoOAS，這是一種新的靜態分析方法，可以直接從 Java 原始碼生成更準確和詳細的 OpenAPI 描述。AutoOAS 的運作分為三個階段：

**原始碼解析：**使用 Spoon 解析 Java 原始碼，識別控制器類別，並根據 Spring 設定檔對其進行分組。
**生成 OpenAPI 方法、參數和回應：**分析控制器類別中的方法定義，提取端點路徑、HTTP 方法、參數、回應碼和資料模型資訊。
**生成 OpenAPI 資料模型：**識別並描述參數和回應中引用的資料模型，包括簡單類型和命名結構描述，並保留繼承資訊。

評估結果
作者在七個真實世界的 Spring Boot 專案上評估了 AutoOAS，並將其效能與其他三種方法進行了比較。結果顯示，AutoOAS 在識別方法、參數和回應方面均取得了最高的精確率和召回率。此外，AutoOAS 是唯一能夠保留資料模型繼承資訊的方法，並且在描述資料模型方面也表現出色。
總結
AutoOAS 為從 Java Spring Boot 原始碼生成準確的 OpenAPI 描述提供了一種有效且可靠的方法。它解決了現有方法的局限性，並為開發人員提供了更準確、詳細和可用的 API 文件。

統計資料

AutoOAS 在識別方法方面取得了 100% 的整體精確率和召回率。
AutoOAS 在識別參數方面取得了 73% 的整體精確率和 69% 的整體召回率。
AutoOAS 在識別回應方面取得了 99% 的整體精確率和 97% 的整體召回率。

從以下內容提煉的關鍵洞見

Generating Accurate OpenAPI Descriptions from Java Source Code

by Alexander Le... 於 arxiv.org 11-01-2024

https://arxiv.org/pdf/2410.23873.pdf

深入探究

AutoOAS 如何處理更複雜的 API 設計模式，例如版本控制和 HATEOAS？

目前 AutoOAS 並未針對版本控制和 HATEOAS 等複雜 API 設計模式提供專門的處理機制。

版本控制： AutoOAS 可能會將不同版本的 API 視為獨立的服務，並為每個版本生成獨立的 OpenAPI 描述。開發者需要手動整合這些描述，或是在程式碼中採用統一的版本控制策略，例如在 URL 路徑或請求標頭中包含版本資訊，以便 AutoOAS 能夠正確識別。

HATEOAS： AutoOAS 目前無法自動生成 HATEOAS 的相關資訊，例如資源間的連結關係。開發者需要手動添加這些資訊到 OpenAPI 描述中。
未來可以考慮擴展 AutoOAS 的功能，使其能夠更好地處理這些複雜的 API 設計模式。例如：

透過分析程式碼中的特定註解或配置，自動識別 API 版本，並將其整合到 OpenAPI 描述中。
透過分析程式碼中的資源操作和關係，自動生成 HATEOAS 的相關資訊。

如果 Java 原始碼中存在程式碼混淆或動態程式碼生成，AutoOAS 的效能會受到什麼影響？

如果 Java 原始碼中存在程式碼混淆或動態程式碼生成，AutoOAS 的效能會受到負面影響，甚至可能無法正確生成 OpenAPI 描述。

程式碼混淆： 程式碼混淆會改變程式碼中的類別、方法和變數名稱，使得 AutoOAS 難以識別 API 相關的資訊。例如，混淆後的程式碼可能無法正確識別 @RestController、@GetMapping 等註解，導致 AutoOAS 無法正確識別控制器和方法。

動態程式碼生成： 動態程式碼生成是指在程式執行期間動態生成程式碼，這類程式碼在編譯期間並不存在，因此 AutoOAS 無法分析。如果 API 的路由、參數、回應等資訊是在執行期間動態生成的，AutoOAS 將無法在 OpenAPI 描述中包含這些資訊。
為了減輕程式碼混淆和動態程式碼生成對 AutoOAS 的影響，可以考慮以下方法：

在程式碼混淆後執行 AutoOAS： 如果可能，在程式碼混淆後執行 AutoOAS，並使用混淆後的程式碼生成 OpenAPI 描述。
使用其他 API 文件工具： 對於動態程式碼生成的 API，可以考慮使用其他 API 文件工具，例如基於執行時資訊生成的工具，或手動編寫 API 文件。

除了自動生成 OpenAPI 描述之外，還有哪些其他方法可以改善 REST API 文件和使用的流程？

除了自動生成 OpenAPI 描述之外，還有許多方法可以改善 REST API 文件和使用的流程：

採用 API 設計規範： 遵循統一的 API 設計規範，例如 Google API 設計指南或 Microsoft REST API 指南，可以提高 API 的一致性和可讀性，方便開發者理解和使用。
編寫清晰易懂的程式碼註解： 使用清晰易懂的語言編寫程式碼註解，說明 API 的用途、參數、回應等資訊，可以幫助開發者更好地理解 API 的行為。
使用 API 文件生成工具： 除了 OpenAPI 描述之外，還可以使用其他 API 文件生成工具，例如 Swagger UI、Redoc 等，將 API 文件以更友好的方式呈現給開發者。
提供 API 測試工具和範例程式碼： 提供 API 測試工具和範例程式碼，可以幫助開發者更快速地理解和使用 API。
建立 API 文件版本控制機制： 隨著 API 的迭代更新，API 文件也需要同步更新，建立 API 文件版本控制機制可以確保開發者使用的是最新版本的 API 文件。
與開發者保持溝通： 定期與開發者溝通，收集他們對 API 文件的意見和建議，並及時解決他們遇到的問題，可以持續改進 API 文件的品質。