創(chuàng)建API文檔后，將其提供給涉眾非常重要。 在理想情況下，此發(fā)布的文檔將具有足夠的靈活性以解決任何最新更改，并且易于分發(fā)（就成本以及完成此操作所需的時間而言）。 為了使這成為可能，我們將利用我在上一篇文章中完成的詳細(xì)介紹API文檔創(chuàng)建過程的內(nèi)容 。 結(jié)合使用Swagger UI模塊和json中已發(fā)布的API文檔，我們可以創(chuàng)建可用于與API交互的簡單HTML文檔。

與Swagger UI集成

Swagger UI的開發(fā)者將其描述為HTML，Javascript和CSS資產(chǎn)的無依賴集??合，可從與Swagger兼容的API動態(tài)生成漂亮的文檔和沙箱。 由于Swagger UI沒有依賴關(guān)系，因此您可以將其托管在任何服務(wù)器環(huán)境或本地計算機(jī)上。 話雖如此，讓我們看一下如何將Swagger文檔提供給Swagger UI。 作為HTML，CSS和JS的靜態(tài)集合，我們可以將其拖放到我們的項目中，而無需修改我們的pom.xml或項目中的任何其他文件。 只需轉(zhuǎn)到GitHub并下載最新文件即可。

完成后，只需提供指向您的API列表的鏈接。 只需打開index.html并用您自己的默認(rèn)API列表URL替換就可以了。 我的示例中的URL看起來像這樣： http://[hostname]:[port]/SpringWithSwagger/rest/api-docs 。 保存此更改并部署應(yīng)用程序和靜態(tài)Swagger UI之后，您應(yīng)該能夠瀏覽API并與之交互。

API文檔

根據(jù)我的示例，我可以訪問以下URL http://localhost:8080/SpringWithSwagger/apidocs/ （由于我選擇的部署方法的性質(zhì)）。 如您所見，Swagger UI僅使用以json格式發(fā)布的數(shù)據(jù)（先前已討論）。 您會看到的第一件事是API列表，它使您可以瀏覽已發(fā)布的API的集合。

當(dāng)您要瀏覽可用的操作時，只需單擊一下所有簡短說明的所有精美彩色列表，便可以知道下一步的導(dǎo)航位置。 顏色在整個清單中保持一致，并很好地補(bǔ)充了操作。

當(dāng)您找到所需的操作時，便該該首先獲取您要查找的信息了。 單擊方法名稱，將顯示完整的方法說明以及參數(shù)和響應(yīng)消息。 但是還有更多原因，因為您可以使用自己的API并測試您的方法。 提供所有必需的參數(shù)并點擊“嘗試一下！” 按鈕，您可以檢查您的應(yīng)用程序服務(wù)器是否已啟動并以預(yù)期的方式運行。 如果您的代碼需要某種類型的文件上傳（就像我的更新用戶的頭像邏輯一樣），那么Swagger UI會提供方便的工具來使其盡可能地容易。

即使您能夠進(jìn)行一些快速的即席測試或檢查，此工具也絕對不適合應(yīng)用程序測試。 它所做的只是以一種易于閱讀的方式提供API文檔，如果您有需要的話，可以自己嘗試該方法（以提高對文檔的理解）。 我發(fā)現(xiàn)這很不錯，因為您需要了解一下操作本身，并且它的可觀察到的行為Swagger UI可以使您滿意，如下所示。

擅長的地方

我真的很喜歡Swagger處理文檔的方式以及Swagger UI呈現(xiàn)文檔的方式。 以下幾點使Swagger非常適合我的API文檔需求：

語言不可知

• 在異構(gòu)環(huán)境中工作或考慮將新語言和工具引入您的項目時，該資產(chǎn)具有極大的價值。

基于注釋的文檔

• 批注將文檔綁定到代碼，以單個生命周期創(chuàng)建一個單元。 這使得管理，發(fā)布和發(fā)布的整個過程變得更加容易，并允許進(jìn)行自動化。

公開進(jìn)行后期處理

• 擁有json形式的中間步驟可讓開發(fā)人員將自定義腳本和轉(zhuǎn)換器附加到流程中，以便根據(jù)涉眾的需要生成各種格式的文檔，例如PDF或Word文檔。

豐富的模塊和組件生態(tài)系統(tǒng)

• 如果瀏覽Swagger的可用模塊和組件，您可能會驚訝于此工具花了多少時間。 那里有許多有用的組件，因此很有可能會找到您認(rèn)為您的項目可能需要或受益的Swagger擴(kuò)展。

外觀精美的UI工具

• 因為我在UI方面不是很有才華，所以我很高興不必?zé)廊绾蝿?chuàng)建，格式化，呈現(xiàn)和交付文檔的方式。 我所需要的只是在源代碼中提供相關(guān)信息，僅此而已。 框架負(fù)責(zé)其余的工作，而我很快就得到了及時的文檔。 鑒于Swagger UI的性質(zhì)，如果需要，可以很容易地向其添加自定義公司標(biāo)識。

試試看！ 選項

• 小事總是讓我開心。 但是我認(rèn)為，對整個團(tuán)隊來說，在文檔中整齊地打包此選項（例如，在需要的地方，需要的時候）非常有益。

不足之處

我不會假裝這是靈丹妙藥，適合所有解決方案。 當(dāng)然，在某些情況下，此類工具不是首選。 鑒于其年輕的年齡，仍有一些事情需要增加/改進(jìn)。 但重要的是要聲明該項目仍在開發(fā)中，并且日漸流行。 話雖這么說，我想指出一些我發(fā)現(xiàn)的問題，這些問題需要深入研究和其他工作。 在我的第一次嘗試中，我將重點關(guān)注三個主要問題。

有條件地訪問某些模型參數(shù)

• 根據(jù)您的需求（以及使用的Swagger版本），您可能會發(fā)現(xiàn)自己需要從Swagger UI和Swagger json隱藏某些模型參數(shù)。 但是，這比我預(yù)期的需要更多的工作，并且需要修改模型屬性。 可以預(yù)期，隨著Swagger及其相關(guān)組件的下一個主要版本的發(fā)布，情況會變得更好，但是在此之前，您不得不手動執(zhí)行此操作。 如果您對如何實現(xiàn)此目標(biāo)感興趣，請查看我的下一篇名為Swagger的Spring Rest API –精調(diào)公開的文檔。

文件上傳及相關(guān)字段

• 您的某些API操作可能需要上傳文件（例如我的頭像更新方法）。 但是，要使操作細(xì)節(jié)看起來像我的示例中所呈現(xiàn)的那樣，需要一點點的手工工作和規(guī)范篩選。 要擺脫與此問題相關(guān)的不需要的參數(shù)，請查看我的下一篇名為Swagger的Spring Rest API –精調(diào)公開的文檔，我將在此詳細(xì)介紹此問題以及如何在此處顯示結(jié)果。

API模型和XML

• Swagger聲稱它是json和XML的朋友。 在操作級別上肯定是正確的，但是，在模型表示方面，XML比json位居第二（由于與XML及其模式有關(guān)的技術(shù)復(fù)雜性）。 當(dāng)前，Swagger UI中的所有API模型都顯示為json實體（json和XML），這迫使我不要在ProductsEndpoint文檔中聲明響應(yīng)類型（在我的SpringWithSwagger示例中，示例使用XML格式的端點）。 這是我尚未完全解決的問題，因此我有意選擇在處理XML時不聲明響應(yīng)類型。

下一步是什么？

如果按照所有步驟進(jìn)行操作，現(xiàn)在應(yīng)該已經(jīng)有適用于您的API的API文檔/沙箱。 在我的下一篇名為Swagger的Spring Rest API的文章中，我將展示如何使用Swagger來微調(diào)已發(fā)布的文檔-微調(diào)公開的文檔。 該微型系列中使用的代碼在GitHub上發(fā)布，并提供了所有討論的功能和工具的示例。 請享受！

翻譯自: https://www.javacodegeeks.com/2014/11/spring-rest-api-with-swagger-exposing-documentation.html

總結(jié)

以上是生活随笔為你收集整理的带有Swagger的Spring Rest API –公开文档的全部內(nèi)容，希望文章能夠幫你解決所遇到的問題。

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