swagger api文檔

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

與Swagger UI集成

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

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

API文檔

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

當(dāng)您要瀏覽可用的操作時(shí)，只需單擊一下所有簡(jiǎn)短說(shuō)明的所有操作的彩色列表，即可知道接下來(lái)要導(dǎo)航到的位置。 顏色在整個(gè)清單中保持一致，并很好地補(bǔ)充了操作。

當(dāng)您找到所需的操作時(shí)，首先是獲取所需信息的時(shí)間。 通過(guò)單擊方法名稱(chēng)，將顯示完整的方法說(shuō)明以及參數(shù)和響應(yīng)消息。 但是還有更多原因，因?yàn)槟梢允褂米约旱腁PI并測(cè)試您的方法。 提供所有必需的參數(shù)并點(diǎn)擊“嘗試一下！” 按鈕，您可以檢查您的應(yīng)用程序服務(wù)器是否已啟動(dòng)并以預(yù)期的方式運(yùn)行。 如果您的代碼需要某種類(lèi)型的文件上傳（就像我的更新用戶(hù)的頭像邏輯一樣），那么Swagger UI會(huì)提供方便的工具來(lái)使其盡可能地容易。

即使您能夠進(jìn)行一些快速的即席測(cè)試或檢查，此工具也絕對(duì)不適合應(yīng)用程序測(cè)試。 它所做的只是以一種易于閱讀的方式呈現(xiàn)API文檔，如果您有需要的話(huà)，可以自己嘗試該方法（以提高對(duì)文檔的理解）。 我發(fā)現(xiàn)這很不錯(cuò)，因?yàn)槟枰私庖幌虏僮鞅旧?#xff0c;并且它的可觀察到的行為Swagger UI可以使您滿(mǎn)意，如下所示。

擅長(zhǎng)的地方

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

語(yǔ)言不可知

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

基于注釋的文檔

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

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

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

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

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

外觀精美的UI工具

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

試試看！ 選項(xiàng)

• 小事總是讓我開(kāi)心。 但是我認(rèn)為，對(duì)整個(gè)團(tuán)隊(duì)來(lái)說(shuō)，在文檔中整齊地打包此選項(xiàng)非常有益（例如，在需要的位置，需要的時(shí)間）。

不足之處

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

有條件訪(fǎng)問(wèn)某些模型參數(shù)

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

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

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

API模型和XML

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

接下來(lái)是什么？

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

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

swagger api文檔

總結(jié)

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

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