我們知道在專案開發階段，介面文件基本上是必備產物了，一般由後端開發人員提供，作為和前端人員進行前後端介面聯調的橋樑，或者與別的專案模組進行互動提供指導等等，介面文件的準確性，實時性，詳細與否等，都會極大的影響前面的操作。那麼如何才能優雅的生成介面文件呢？

其實對於做開發的大多數人來說，多多少少都聽過swagger，它是一個較為流行的介面文件管理工具，使用起來非常方便。所以大多數人都會使用swagger來生成介面文件，但是今天我要介紹另外一種生成介面文件的方式。通過swagger外掛(如jar包)解析編寫了介面註解的java程式碼, 而後通過生成的swagger.json檔案解析出介面資訊並匯入介面文件管理工具yapi（yapi是去哪兒的大前端團隊開發，基於react+antd的一套介面文件管理工具）。具體操作步驟如下：

圖中的@POST, @ApiResponses, @Path等意思都很明顯，因為我的java只有一點點語法基礎, 所以理解可能有點出入, 我這裡簡單理解為註釋的意思。如有不對求指教。

這個類裡面, 有user和login屬性, 分別給屬性加了類似這樣的註解

解決好pom檔案的依賴後。在專案目錄執行:mvn clean compile

yapi是去哪兒的大前端團隊開發，基於react+antd的一套介面文件管理工具，可以自己下載體驗下，真心不錯。至於不需要yapi, 鍾愛原生swagger的童鞋, 也可以直接將swagger.json放入你的本地swaggerUI中檢視介面文件。

那麼其配置來說也相對的簡單易用，這也是其為什麼受到了眾多後端開發者喜愛的原因，當然了Swagger不僅僅支援java，還支援多種語言，而且目前主流的語音對於Swagger的支援也已經做的非常好了！

以上就是筆者分享的兩款目前主流的介面文件工具，個人感覺生成的文件都是比較優雅和易懂的，而且排版佈局都是非常良好。

很簡單，我建議使用Swagger，一個很簡單的介面文件生成器。Swagger是使用OpenAPI規範（OAS）開發API時使用最廣泛的工具生態系統。Swagger包含開源和專業工具，幾乎可以滿足每種需求和用例。

Swagger UI是Swagger的一部分，它是一個開放原始碼工具，可生成記錄由Swagger規範生成的API的網頁。這些API的UI呈現是使用者友好的並且易於理解，所有邏輯複雜性都隱藏在屏幕後面。這使開發人員能夠執行和監視他們傳送的API請求以及收到的結果，從而使它成為開發人員，測試人員和終端使用者瞭解他們正在測試的端點的好工具。

當您開啟網頁時，瀏覽器將從Web伺服器載入網頁，並觸發對API伺服器的請求以從資料庫獲取資料。SwaggerUI是從OpenAPI規範中定義的任何API自動生成的，可以在瀏覽器中檢視。

假設要將Swagger UI新增到我們的專案中，您需要向pom.xml檔案中再新增一個依賴項（如果尚未新增）。

然後，使用SwaggerUI轉到URL：http：// <主機>：<埠> /swagger-

ui.html

我們還可以使用Swagger UI線上測試API。讓我們看一個例子。我們將使用示例

http://petstore.swagger.io/

我們要做的第一件事是將API平臺匯入Swagger UI，Swagger API平臺可以是YAML或JSON格式。在這種情況下，我們將使用JSON。

首次執行測試時，由於auth，標頭或查詢引數之類的HTTP請求要求，它們可能會失敗。展開/ auth，單擊“ 試用”按鈕，然後輸入您的帳戶資訊。

所以到此為止你已經完全知道如何使用Swagger，Swagger工具徹底改變了API的設計和構建方式。但是隨著持續交付發展，並且期望開發人員提高他們交付的API的質量和可讀性，對我們來說，需要一個簡單的API測試和文件生成工具的需求已變得顯而易見的事情～

簡潔，可複用，不累贅，有引數說明和功能說明，有必要註釋，更高階的是效率和安全！做到這些，可以稱得上是優雅的介面了！實用簡潔！