確定在記錄REST API時(shí)選擇哪種Java框架可能很麻煩。 在本博文中，我們將簡(jiǎn)要比較我們自己使用的REST Web服務(wù)的三種文檔框架，以及它們?nèi)绾闻cSpring框架（這是Foreach最常使用的Java框架）集成。 這些是RESTful API建模語(yǔ)言（RAML），Swagger UI和Spring REST Docs。

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

RESTful API建模語(yǔ)言（RAML）

RAML是一個(gè)單獨(dú)的文檔，與您作為開(kāi)發(fā)人員需要手動(dòng)維護(hù)的項(xiàng)目一起保存。 在默認(rèn)的RAML配置中，幾乎不會(huì)自動(dòng)執(zhí)行任何操作。 但是，借助隨附的插件生態(tài)系統(tǒng)，很容易擴(kuò)展RAML使其表現(xiàn)出所需的行為。

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

• API Workbench ：“一個(gè)用于設(shè)計(jì)，構(gòu)建，測(cè)試，記錄和共享RESTful HTTP API的豐富，功能齊全的集成開(kāi)發(fā)環(huán)境（IDE）”；
• RAML Java客戶(hù)端生成器 ：根據(jù)RAML文檔自動(dòng)生成Java客戶(hù)端的工具；
• RAML2HTML ：一種Node.js工具，用于生成用戶(hù)友好HTML文檔。

在構(gòu)建過(guò)程中定義的額外步驟中，書(shū)面文檔將從RAML格式轉(zhuǎn)換為人類(lèi)可讀的文本（或HTML）。

過(guò)去，RAML曾經(jīng)是Java中我們首選的文檔框架，但是現(xiàn)在我們發(fā)現(xiàn)了一些替代方案，因此開(kāi)始越來(lái)越少地使用RAML。 另外，使用RAML很難編寫(xiě)也易于使用的完整文檔（因?yàn)镽AML中的所有文檔都需要手動(dòng)編寫(xiě)）。 此外，我們通常會(huì)在對(duì)API進(jìn)行調(diào)整后忘記更新文檔。 通過(guò)使用一個(gè)框架可以解決此問(wèn)題，在該框架中，大多數(shù)API更改都是自動(dòng)記錄的，而不是手動(dòng)記錄的。

招搖UI

相反，Swagger UI會(huì)自動(dòng)生成所有內(nèi)容。 在此框架中，Swagger與Swagger UI和Springfox協(xié)同工作以在運(yùn)行時(shí)生成文檔。 該框架包含三個(gè)組件：

• Swagger是規(guī)范的一部分：一組描述RESTful服務(wù)的規(guī)則（與RAML相當(dāng)）；
• Swagger UI是呈現(xiàn)部分：它呈現(xiàn)用戶(hù)友好HTML（就像RAML2HTML一樣），并允許用戶(hù)在沒(méi)有任何客戶(hù)端基礎(chǔ)結(jié)構(gòu)的情況下測(cè)試服務(wù)，因?yàn)樗鼤?huì)基于Swagger服務(wù)規(guī)范自動(dòng)生成測(cè)試客戶(hù)端；
• Springfox是“生成”部分：它與服務(wù)交互（通過(guò)注釋，包括它自己的注釋和Spring注釋），以在運(yùn)行時(shí)自動(dòng)生成文檔。

這三個(gè)組件將檢查您的代碼以確定需要記錄的內(nèi)容。 他們既可以生成文檔（通過(guò)動(dòng)態(tài)網(wǎng)站），也可以通過(guò)Swagger UI進(jìn)行“測(cè)試服務(wù)調(diào)用”。 服務(wù)調(diào)用的工作方式與例如Postman相同，唯一的區(qū)別在于，該庫(kù)可以通過(guò)從應(yīng)用程序的文檔化部分向服務(wù)發(fā)送原始請(qǐng)求來(lái)在瀏覽器中工作。

由于Springfox將在運(yùn)行時(shí)負(fù)責(zé)生成，因此無(wú)需定義額外的構(gòu)建步驟（與RAML和Spring REST Docs不同，在其中需要單獨(dú)的構(gòu)建步驟）。

當(dāng)我們第一次開(kāi)始使用它時(shí)，Swagger堆棧似乎很棒。 我們幾乎沒(méi)有（人工）勞動(dòng)，因?yàn)橐磺卸际亲詣?dòng)生成的。 同時(shí)，我們?nèi)匀豢梢酝ㄟ^(guò)在代碼中添加注釋來(lái)調(diào)整文檔。 我們認(rèn)為，這既是優(yōu)點(diǎn)也是缺點(diǎn)。 因?yàn)殡m然Swagger UI確實(shí)易于使用，但是我們對(duì)生成的文檔的控制沒(méi)有我們想要的那么多。

Spring REST文件

Spring REST Docs是Spring生態(tài)圈的一部分，可根據(jù)您的單元測(cè)試生成AsciiDoc片段。 這些片段可以包含在手寫(xiě)的AsciiDoc中，以為您的API匯編文檔。

為此，您可以指定希望從對(duì)MockMVC端點(diǎn)的調(diào)用中檢索的字段，并定義要在文件系統(tǒng)上創(chuàng)建生成的代碼段的位置。 如果期望的字段與結(jié)果不完全一致，則您的測(cè)試將失敗，這意味著與文檔相關(guān)的單元測(cè)試也將作為代碼的額外檢查。

在構(gòu)建過(guò)程的后期，您將需要定義一個(gè)額外的步驟，通過(guò)將生成的代碼片段與手寫(xiě)索引頁(yè)結(jié)合起來(lái)，生成人類(lèi)可讀HTML文件，從而促進(jìn)文檔的傳播。

我們?cè)谝粋€(gè)項(xiàng)目中使用了Spring REST Docs，該項(xiàng)目需要外部參與者使用API??和常規(guī)文檔。 他們使用自己的測(cè)試工具，因此不希望為他們提供基于瀏覽器的界面來(lái)測(cè)試該界面。 我們之所以選擇REST Docs框架，是因?yàn)?#xff08;a）它也可以成為我們集成測(cè)試的一部分，并且（b）我們可以輕松地將其與所有其他非技術(shù)性文檔結(jié)合在一起。

總覽

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

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

無(wú)論您選擇什么，每個(gè)單獨(dú)的框架都足以以明確的方式將Web服務(wù)的合同傳達(dá)給其他開(kāi)發(fā)人員-這最終是這些框架的目標(biāo)。

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

總結(jié)

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

如果覺(jué)得生活随笔網(wǎng)站內(nèi)容還不錯(cuò)，歡迎將生活随笔推薦給好友。