javascript
带有Swagger的Spring Rest API –公开文档
創(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)行自動化。
- 擁有json形式的中間步驟可讓開發(fā)人員將自定義腳本和轉(zhuǎn)換器附加到流程中,以便根據(jù)涉眾的需要生成各種格式的文檔,例如PDF或Word文檔。
- 如果瀏覽Swagger的可用模塊和組件,您可能會驚訝于此工具花了多少時間。 那里有許多有用的組件,因此很有可能會找到您認(rèn)為您的項目可能需要或受益的Swagger擴(kuò)展。
- 因為我在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)注三個主要問題。
- 根據(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)公開的文檔。
- 您的某些API操作可能需要上傳文件(例如我的頭像更新方法)。 但是,要使操作細(xì)節(jié)看起來像我的示例中所呈現(xiàn)的那樣,需要一點點的手工工作和規(guī)范篩選。 要擺脫與此問題相關(guān)的不需要的參數(shù),請查看我的下一篇名為Swagger的Spring Rest API –精調(diào)公開的文檔,我將在此詳細(xì)介紹此問題以及如何在此處顯示結(jié)果。
- 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)容,希望文章能夠幫你解決所遇到的問題。
- 上一篇: linux系统安装在u盘(linux系统
- 下一篇: 带有Swagger的Spring Res