讀處

由於上次分享在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 不太一樣

本文只是簡單撰寫，如有更多進階設定，需要再額外查一下文件