由於上次分享在Spring Boot 專案當中加入Swagger (點選進入到該連結看更多詳細說明)
當時分享時還停留在 Spring Boot 2.x 版本
不過最近 Spring Boot 更新至 3.x 版本後，我發現按照上次分享的方式去設定
會無法正常啟用 Swagger，因此今天再來分享與紀錄，在 SpringBoot 3.x 應該如何去設定並啟用 Swagger
簡單說明一下環境規格
我所使用的 Spring Boot 版本為3.0.5，Java使用17的版本
首先，Spring Boot 3.x 版本所要導入的相依需更改為springdoc-openapi-starter-webmvc-ui
可以到https://mvnrepository.com/artifact/org.springdoc/springdoc-openapi-starter-webmvc-ui 去複製dependency
然後把他加入到pom.xml的相依性當中，以下是我加入後的截圖畫面
加入 maven 相依以後，我們就可以開始設定Swagger
一樣我習慣在專案當中建立一個 config 的 package ，作為放置設定相關的 Class
並在 config 的 package 下建立 SwaggerConfig
設定的部分，以上圖為例分兩個部分:
第一個部分是@OpenAPIDefinition
這邊主要就是設定一下Swagger的資訊，包含標題、描述和版本號
當然也可以設定相關聯絡人資訊等，有需要可以在查一下寫法
這邊我是只有設定一些比較基礎的部分
第二個部分是安全性的設定
因為有些API，可能需要再 Header 帶入 token 做認證才能操作該API
由於我採用的是 JWT 認證方式，所以設定方式可以參考上方圖片所示
如果有安全性部分的設定的話，在啟用Swagger的時候，就可以在Swagger的右上方看到一個Authorize的按鈕
按下按鈕後，就會跳出視窗，就可以把token值帶到 header 當中
接著就可以在各別 Controller 上方加入 @Tag，用來標示該 Controller 的主題和描述說明
另外也可以透過 @Operation 的標籤來說明每個 REST API 的功用
等專案起來以後，在瀏覽器當中使用 http://localhost:8080/swagger-ui/index.html 這個連結，就可以打開Swagger的網頁畫面
如下圖所示為使用這些標籤後的呈現樣子
因為在Spring Security 可以設定哪些 API 是可以不用作授權認證，上面的範例就是不需要帶入 token 就可以執行的 API
若是該 API 是需要帶入 token 認證才能執行的話，可以使用 @SecurityRequirement 標籤
name 的部分則是要和我們在 config 當中設定 @SecurityScheme 裡所使用的名字一樣
這樣一來，在 Swagger 的畫面上就會在 API 後面看到一個鎖的圖示
當你要執行這個 API 時若還沒有設定 token 的值，他則會跳出讓你設定的視窗
當設定 token 值以後，執行 API 就可以看到 Swagger 在打 API 的時候，自動幫我們加上得 Authorization 的 header設定
Spring Boot 3.x 版本以後的 Swagger 的概念上是和以前一樣的
只是在設定上，以及需要載入的 lib 不太一樣
本文只是簡單撰寫，如有更多進階設定，需要再額外查一下文件
留言列表
