確定在記錄REST API時選擇哪種Java框架可能很麻煩。 在本博文中，我們將簡要比較我們自己使用的REST Web服務的三種文檔框架，以及它們如何與Spring框架（這是Foreach最常使用的Java框架）集成。 這些是RESTful API建模語言（RAML），Swagger UI和Spring REST Docs。

在每一部分中，我們將對所討論的文檔框架進行高層概述。 我們將簡要描述文檔框架如何與Spring集成以及如何在您的文檔中使用該框架影響構建周期。

RESTful API建模語言（RAML）

RAML是一個單獨的文檔，與您作為開發人員需要手動維護的項目一起保存。 在默認的RAML配置中，幾乎不會自動執行任何操作。 但是，借助隨附的插件生態系統，很容易擴展RAML使其表現出所需的行為。

該文檔框架的生態系統非常活躍，其插件啟用了各種功能，例如：

• API Workbench ：“一個用于設計，構建，測試，記錄和共享RESTful HTTP API的豐富，功能齊全的集成開發環境（IDE）”；
• RAML Java客戶端生成器 ：根據RAML文檔自動生成Java客戶端的工具；
• RAML2HTML ：一種Node.js工具，用于生成用戶友好HTML文檔。

在構建過程中定義的額外步驟中，書面文檔將從RAML格式轉換為人類可讀的文本（或HTML）。

過去，RAML曾經是Java中我們首選的文檔框架，但是現在我們發現了一些替代方案，因此開始越來越少地使用RAML。 另外，使用RAML很難編寫也易于使用的完整文檔（因為RAML中的所有文檔都需要手動編寫）。 此外，我們通常會在對API進行調整后忘記更新文檔。 通過使用一個框架可以解決此問題，在該框架中，大多數API更改都是自動記錄的，而不是手動記錄的。

招搖UI

相反，Swagger UI會自動生成所有內容。 在此框架中，Swagger與Swagger UI和Springfox協同工作以在運行時生成文檔。 該框架包含三個組件：

• Swagger是規范的一部分：一組描述RESTful服務的規則（與RAML相當）；
• Swagger UI是呈現部分：它呈現用戶友好HTML（就像RAML2HTML一樣），并允許用戶在沒有任何客戶端基礎結構的情況下測試服務，因為它會基于Swagger服務規范自動生成測試客戶端；
• Springfox是“生成”部分：它與服務交互（通過注釋，包括它自己的注釋和Spring注釋），以在運行時自動生成文檔。

這三個組件將檢查您的代碼以確定需要記錄的內容。 他們既可以生成文檔（通過動態網站），也可以通過Swagger UI進行“測試服務調用”。 服務調用的工作方式與例如Postman相同，唯一的區別在于，該庫可以通過從應用程序的文檔化部分向服務發送原始請求來在瀏覽器中工作。

由于Springfox將在運行時負責生成，因此無需定義額外的構建步驟（與RAML和Spring REST Docs不同，在其中需要單獨的構建步驟）。

當我們第一次開始使用它時，Swagger堆棧似乎很棒。 我們幾乎沒有（人工）勞動，因為一切都是自動生成的。 同時，我們仍然可以通過在代碼中添加注釋來調整文檔。 我們認為，這既是優點也是缺點。 因為雖然Swagger UI確實易于使用，但是我們對生成的文檔的控制沒有我們想要的那么多。

Spring REST文件

Spring REST Docs是Spring生態圈的一部分，可根據您的單元測試生成AsciiDoc片段。 這些片段可以包含在手寫的AsciiDoc中，以為您的API匯編文檔。

為此，您可以指定希望從對MockMVC端點的調用中檢索的字段，并定義要在文件系統上創建生成的代碼段的位置。 如果期望的字段與結果不完全一致，則您的測試將失敗，這意味著與文檔相關的單元測試也將作為代碼的額外檢查。

在構建過程的后期，您將需要定義一個額外的步驟，通過將生成的代碼片段與手寫索引頁結合起來，生成人類可讀HTML文件，從而促進文檔的傳播。

我們在一個項目中使用了Spring REST Docs，該項目需要外部參與者使用API??和常規文檔。 他們使用自己的測試工具，因此不希望為他們提供基于瀏覽器的界面來測試該界面。 我們之所以選擇REST Docs框架，是因為（a）它也可以成為我們集成測試的一部分，并且（b）我們可以輕松地將其與所有其他非技術性文檔結合在一起。

總覽

如您所見，“最佳”文檔框架取決于您期望文檔框架能夠完成的工作。 如果您希望不需要大量的“靜態”文檔（即，如果可以自動生成所有內容），則開箱即用即可輕松使用Swagger UI。

另一方面，如果您需要提供單個文檔，或者只想對文檔進行更多控制，則最好使用RAML或Spring REST Docs之類。 而且，已經證明與Spring REST Docs中的測試集成非常有用。

無論您選擇什么，每個單獨的框架都足以以明確的方式將Web服務的合同傳達給其他開發人員-這最終是這些框架的目標。

翻譯自: https://www.javacodegeeks.com/2019/01/comparing-java-documentation-frameworks.html

總結

以上是生活随笔為你收集整理的比较Java REST文档框架的全部內容，希望文章能夠幫你解決所遇到的問題。

如果覺得生活随笔網站內容還不錯，歡迎將生活随笔推薦給好友。