讀處

後端在開發 API 的時候，可以透過 Swagger 來測試 API

而Swagger也可以做為前後端開發團隊的一份 Rest API 文件

Swagger 是一套方常方便的 API 工具

除了可以省下寫額外寫 API 文件的時間，在寫程式的時候，就一邊建置文件了

也可以透過 Swagger 的 web UI 介面來進行執行與測試 API，不需要額外再使用像是Postmen、API Tester等工具來測試API

接下來我們就要開始介紹與紀錄，如何在 Spring Boot 當中加入 Swagger

首先要先在 pom.xml 當中加入 swagger 的 maven 相依

可以到 https://mvnrepository.com/artifact/io.springfox/springfox-boot-starter/3.0.0 去複製 dependency

加完 dependency 後，可以把 application run 起來

等專案起來以後，在瀏覽器當中使用 http://localhost:8080/swagger-ui/index.html 這個連結，就可以打開Swagger的網頁畫面

在我們還沒有做任何的配置設定下，其畫面如下

接著我們用 get product 來測試一下 API 執行的狀況

找到我們要執行的 API 按旁邊的 Try it out

執行 API 完後，我們就可以往下拉一點看 API 的執行結果

可以看到 API 的狀態是200，然後並且查看 response 的詳細內容

接著我們可以來做一些簡單的配置，在專案下新增一個 config 的 package (非必要，個人喜歡將相關的config放在同一個目錄下)

新增一個 Swgger 設置的class (class name 隨意)

將 class 貼上 @Configuration 的標籤，使Spring boot 啟動時會過來吃設邊的設定

在這個設置上有幾個重點，首先是對這份文件寫上一些基本資訊

像是標題、描述、聯絡人資訊、版本號 等等

接著是設定是否啟用Swagger，若將來想要把Swagger關掉只需要設成false

以及設定我們指定的 api 實作路徑位置，一般我在開發的時候都會將相關的 api 實作放在 controller 下

剛剛尚未配置這個設定時，當我們啟用Swagger就會發現有一個basic-error-controller

這個controller並非我們這個專案實作的，但是卻也呈現出來

設定完成後，再次執行 application 打開 swagger

就可以發現多了一些基本資訊的呈現，以及過濾掉非我們自己專案實作的controller

接著我可以針對下方API的資訊再做一些設定

我們可以在Conller 的 Class 上加上 @Api(tags = "帳號功能") 註解，用來表示這支Controller主題

並且也可以在各個 API 實作上加上 @ApiOperation 的註解，用來表示每支API的功用以及簡易說明

改完後就可以再次執行 application 打開 swagger

這一次打開 swagger 後就會發現，畫面更加易讀，而不是只有顯示controller的名字

而是更加容易清楚每個區塊以及每一支的API功能

原始碼可以參考我的github: https://github.com/lakesd6531/springboot-E-commerce