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

與Swagger UI集成

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

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

API文檔

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

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

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

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

擅長的地方

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

語言不可知

• 在異構環境中工作或考慮將新語言和工具引入您的項目時，該資產具有極大的價值。

基于注釋的文檔

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

公開進行后期處理

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

豐富的模塊和組件生態系統

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

外觀精美的UI工具

• 因為我在UI方面不是很有才華，所以我很高興不必煩惱如何創建，格式化，呈現和交付文檔的方式。 我所需要的只是在源代碼中提供相關信息，僅此而已。 框架負責其余的工作，而我很快就得到了及時的文檔。 鑒于Swagger UI的性質，如果需要，可以很容易地向其添加自定義公司標識。

試試看！ 選項

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

不足之處

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

有條件地訪問某些模型參數

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

文件上傳及相關字段

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

API模型和XML

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

下一步是什么？

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

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

總結

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

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