SpringDoc 教學-入門
最近在幫 Hana 引擎加入 openAPI3(swagger3)，想說寫個教學文章。
預計會有兩篇文章漸進式的說明如何導入 openAPI3，分別是:
- 如何導入 openAPI3
- 如何客製化 swagger 的網頁內容，如標題、和 API 分組。
今天的文章是如何快速導入 openAPI3 ，並且設定各 API 的說明和 request response 設定 example。
正文
主要有三個步驟:
- 導入 springDoc lib 和顯示網頁
- 設定 controller、API 說明
- 設定 request 、 response 參數說明與 example
讓我們一個一個開始吧。ヽ(✿ﾟ▽ﾟ)ノ
步驟1: 導入 springDoc lib 和顯示網頁
首先所有的 java lib 都是到 maven repository 取得，因此我們只要到 maven repository 尋找 SpringDoc OpenAPI Starter WebMVC UI ，或者按這個網址: https://mvnrepository.com/artifact/org.springdoc/springdoc-openapi-starter-webmvc-ui
打開網址 -> 選擇版本就可以看到下面的圖片，在紅色框框中依照專案的依賴管理工具，選擇自己需要的格式並且複製下來。
因為 Hana 引擎是使用 gradle ，因此我複製 gradle 下來並添加到自己專案的 build.gradle (如果是 maven 的話就是 pom.xml) 。
添加依賴之後啟動 spring boot，啟動後開瀏覽器到該專案的網址並且在後面加上 /swagger-ui/index.html#/ 就可以看到專案導入 openAPI 了。
步驟2: 設定 controller、API 說明
在上圖我們可以看到 save-data-controller 和 chat-controller 事實上這兩個都是 springDoc 依照 controller class name 的駝峰顯示出來的。
步驟 2-1 修改 contoller 說明
我們接下來要把它改成看得懂的說明。
其實非常簡單，只要在該 controller 前面加上 tag annotations 就好了，如下圖紅色框框的部分:
加上去之後我們再到 openAPI 看，可以看到已經變成我們 tag 的內容了:
步驟 2-2 修改 API 的說明
完成之後我們打開一個 API 來看，會發現該 API 像下圖一樣沒有任何說明。
因此我們需要幫 controller 裡的方法加入 @Operation annotations 來幫助 openAPI 網頁顯示該 API 的說明，如下圖:
加入之後我們再看一下 openAPI，可以看到新增了說明:
順道一提，它支援使用 markdown ，因此可以透過 markdown 在上面使用標題、表格等等。
步驟3-1: 修改 PATH 、 header 的參數說明與 example
這部分也非常簡單只要在 controller 裡的input參數加上 @Schema 就好了，如下圖:
加上去之後再去看 openAPI 就會得到這樣的效果:
步驟 3-2 修改 request 和 response 的參數說明和 example
這部分其實跟 3-1 很像，這邊我們找一個 post API 來說明，如下圖:
目前大部分的springboot API 都是使用傳入物件當作 request ，return 的物件是 response，因此我們直接進到 request 類別看，只要加上下圖紅色框的 annotations 即可:
之後我們去 openAPI 網頁看，可以看到已經有 example value 已經有範例 request:
確認之後我們點 schema 看看，可以看到也已經加入說明了:
response 也是一樣的做法，因此這邊就不再說明。
步驟 3-3 在 openAPI 說明該參數必填
加上去之後我們看一下 swagger ，可以看到被標記為不允許為空:
步驟 3 補充:
如果今天使用的是 record 的話呢，其實也是一樣的做法，請見下圖:
結語
以上就是所有設定 openAPI 最基礎的設定了，下次會說如何針對 openAPI 最更進一步的設定，還請大家期待一下吧d(`･∀･)b
留言
張貼留言