?? 作者主頁： 有來技術
?? 開源項目： youlai-mall ?? vue3-element-admin ?? youlai-boot
?? 倉庫主頁： Gitee ?? Github ?? GitCode
?? 歡迎點贊 ?? 收藏 ?留言 ?? 如有錯誤敬請糾正！
開局一張圖
前言
youlai-mall 開源微服務商城新版本基于 Spring Boot 3 和 Java 17，同時采用 Knife4j 4.3。與以前版本不同的是，新版本的 Knife4j 不再依賴 Springfox 框架（該框架于2020年停止更新）作為基礎的 OpenAPI3 規(guī)范，而選擇了 SpringDoc 作為底層依賴框架的 OpenAPI3 規(guī)范的實現(xiàn)。因此，相對于以前的版本，新版本存在較大的差異。
在新版本中，您可以參考 Knife4j 官網(wǎng) 進行適配和升級。本文將介紹新版本中 Knife4j 4.3 和微服務的整合、 Spring Cloud Gateway 網(wǎng)關聚合，以及如何自動填充 Spring Authorization Server 的自定義擴展的 OAuth2 密碼模式的 access_token。
Spring Cloud 整合 Knife4j
這里的 Spring Cloud 微服務是除了網(wǎng)關(youlai-gateway)之外的其他服務，像系統(tǒng)服務(youlai-system)和商城服務(mall-*)
pom.xml
添加 knife4j 的 maven 依賴，參考 Spring Boot 3 整合 Knife4j
<dependency>
<groupId>com.github.xiaoymin</groupId>
<artifactId>knife4j-openapi3-jakarta-spring-boot-starter</artifactId>
<version>4.3.0</version>
</dependency>
application.yml
除了 packages-to-scan 掃描接口包路徑，其他默認即可，參考 Spring Boot 3 整合 Knife4j
spring:
security:
oauth2:
authorizationserver:
# OAuth2 認證路徑
token-uri: http://localhost:9999/youlai-auth/oauth2/token
# springdoc-openapi 項目配置
springdoc:
swagger-ui:
path: /swagger-ui.html
tags-sorter: alpha
operations-sorter: alpha
api-docs:
path: /v3/api-docs
group-configs:
- group: 'default'
paths-to-match: '/**'
packages-to-scan:
# 配置接口文檔掃描包路徑，每個服務的路徑不同，下面是系統(tǒng)服務(youlai-system)的包路徑
- com.youlai.system.controller
# knife4j的增強配置，不需要增強可以不配
knife4j:
enable: false
setting:
language: zh_cn
SwaggerConfig.java
package com.youlai.system.config;
import io.swagger.v3.oas.models.Components;
import io.swagger.v3.oas.models.OpenAPI;
import io.swagger.v3.oas.models.info.Info;
import io.swagger.v3.oas.models.info.License;
import io.swagger.v3.oas.models.security.OAuthFlow;
import io.swagger.v3.oas.models.security.OAuthFlows;
import io.swagger.v3.oas.models.security.SecurityRequirement;
import io.swagger.v3.oas.models.security.SecurityScheme;
import org.springframework.beans.factory.annotation.Value;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import org.springframework.http.HttpHeaders;
/**
* Swagger 配置類
* <p>
* 基于 OpenAPI 3.0 規(guī)范 + SpringDoc 實現(xiàn) + knife4j 增強
*
* @author haoxr
* @since 3.0.0
*/
@Configuration
public class SwaggerConfig {
/**
* OAuth2 認證 endpoint
*/
@Value("${spring.security.oauth2.authorizationserver.token-uri}")
private String tokenUrl;
/**
* OpenAPI 配置（元信息、安全協(xié)議）
*/
@Bean
public OpenAPI apiInfo() {
return new OpenAPI()
.components(new Components()
.addSecuritySchemes(HttpHeaders.AUTHORIZATION,
new SecurityScheme()
// OAuth2 授權模式
.type(SecurityScheme.Type.OAUTH2)
.name(HttpHeaders.AUTHORIZATION)
.flows(new OAuthFlows()
.password(
new OAuthFlow()
.tokenUrl(tokenUrl)
.refreshUrl(tokenUrl)
)
)
// 安全模式使用Bearer令牌（即JWT）
.in(SecurityScheme.In.HEADER)
.scheme("Bearer")
.bearerFormat("JWT")
)
)
// 接口全局添加 Authorization 參數(shù)
.addSecurityItem(new SecurityRequirement().addList(HttpHeaders.AUTHORIZATION))
// 接口信息定義
.info(new Info()
.title("系統(tǒng)服務")
.version("3.0.0")
.description("用戶、角色、菜單、部門、字典等接口")
.license(new License().name("Apache 2.0")
.url("https://www.apache.org/licenses/LICENSE-2.0"))
);
}
}
訪問單服務接口文檔
訪問 Knife4j 的文檔地址：http://ip:port/doc.html即可查看文檔
系統(tǒng)服務 (youlai-system) 的接口文檔地址 http://localhost:8800/doc.html ，訪問頁面如下：
Spring Cloud Gateway 網(wǎng)關聚合
參考 Knife4j 官方文檔：Spring Cloud Gateway 網(wǎng)關聚合
Knife4j 官方提供 手動配置 和 服務發(fā)現(xiàn) 兩種聚合方式，如果微服務數(shù)量少且有定制化文檔需求建議 手動配置，否則一般還是推薦服務發(fā)現(xiàn)的方式，可以避免每次新增一個服務還得手動去添加配置的煩惱。
這里使用的是 服務發(fā)現(xiàn) 聚合方式，如果手動請參考官方配置（很詳細）
pom.xml
<dependency>
<groupId>com.github.xiaoymin</groupId>
<artifactId>knife4j-gateway-spring-boot-starter</artifactId>
<version>4.3.0</version>
</dependency>
application.yml
spring:
cloud:
gateway:
discovery:
locator:
# 啟用服務發(fā)現(xiàn)
enabled: true
lower-case-service-id: true
# 網(wǎng)關路由
routes:
- id: 系統(tǒng)服務
uri: lb://youlai-system
predicates:
- Path=/youlai-system/**
filters:
- StripPrefix=1
# knife4j 網(wǎng)關聚合
knife4j:
gateway:
enabled: true
# 指定服務發(fā)現(xiàn)的模式聚合微服務文檔，并且是默認 default 分組
strategy: discover
discover:
# OpenAPI 3.0 規(guī)范
version: openapi3
enabled: true
訪問網(wǎng)關聚合接口文檔
訪問 Knife4j 的文檔地址：http://ip:port/doc.html即可查看文檔
網(wǎng)關(youlai-gateway) 的接口文檔地址 http://localhost:9999/doc.html ，訪問頁面如下圖：
接口測試
接下來做一個 OAuth2 登錄認證（Spring Authorization Server 擴展的 OAuth2 密碼模式），認證成功拿到訪問令牌(access_token) 去請求獲取登錄用戶信息接口測試 。
認證成功之后，再去打開其他接口會請求頭會自動攜帶訪問令牌。
登錄認證
點擊接口文檔左側(cè)菜單欄 Authorize 打開認證頁面，填寫圖示 OAuth2 密碼模式授權認證參數(shù)
?? 特別提醒: Knife4j 自動填充請求頭前提需要數(shù)據(jù)原生返回，那么什么是原生數(shù)據(jù)格式？
-
??原生數(shù)據(jù)格式
{ "access_token": "eyJraWQiOiJlNTg1NTQ3MS02ZDlmLTRkOWEtODJlNi1mN2QyNjY4YjhhZDgiLCJhbGciOiJSUzI1NiJ9.xxx.xxx", "refresh_token": "oYQz7UA4jafCfYZN7BW1cX6Kn-QGxNf1XIxKp-xxx", "token_type": "Bearer", "expires_in": 86400 } -
?包裝數(shù)據(jù)格式
自定義數(shù)據(jù)格式，像包含了業(yè)務碼的，這種 Knife4j 是無法解析的，更沒法去自動填充了。
{ "code": "00000", "data": { "access_token": "eyJraWQiOiJlNTg1NTQ3MS02ZDlmLTRkOWEtODJlNi1mN2QyNjY4YjhhZDgiLCJhbGciOiJSUzI1NiJ9.xxx.xxx", "refresh_token": "ImW57MWPEBQpcNpuPsX1l5eJCDtyoBMz-xxx", "token_type": "Bearer", "expires_in": 86400 }, "msg": "一切ok" }
client 是代碼中為測試接口預留的一個客戶端ID，具體可以看下 MyAuthenticationSuccessHandler 這個類的處理
獲取用戶信息
認證成功之后，打開 獲取登錄用戶信息 接口 ，點擊請求頭部可以看到訪問令牌已經(jīng)自動填充到請求頭的 Authorization 參數(shù)中了。
點擊發(fā)送，可以看到數(shù)據(jù)成功返回。
輸入錯誤的訪問令牌，提示 “token無效或已過期”，符合預期效果。
結(jié)語
這篇文章首先介紹了如何將 Spring Cloud 微服務與 Knife4j 4.3 集成，借助 Spring Cloud Gateway 網(wǎng)關聚合各個服務的接口文檔，實現(xiàn)了更統(tǒng)一的管理方式。最后，我們還探討了如何在整合后的接口文檔中測試 Spring Authorization Server 擴展的 OAuth2 密碼模式認證接口，一旦認證成功，Knife4j 會自動填充訪問令牌，使您能夠輕松地訪問其他接口。文章來源：http://www.zghlxwxcb.cn/news/detail-716497.html
到此，youlai-mall 新版本接口文檔的整合和調(diào)試教程結(jié)束。希望這篇文章對您有所幫助，能夠幫助您避免在使用新版本時遇到各種問題。文章來源地址http://www.zghlxwxcb.cn/news/detail-716497.html
源碼
| Github | Gitee | |
|---|---|---|
| 開源組織 | 有來開源組織 | 有來開源組織 |
| 后端 | youlai-mall ?? | youlai-mall ?? |
| 前端 | mall-admin?? | mall-admin ?? |
| 移動端 | mall-app ?? | mall-app ?? |
到了這里，關于Spring Cloud Gateway + Knife4j 4.3 實現(xiàn)微服務網(wǎng)關聚合接口文檔的文章就介紹完了。如果您還想了解更多內(nèi)容，請在右上角搜索TOY模板網(wǎng)以前的文章或繼續(xù)瀏覽下面的相關文章，希望大家以后多多支持TOY模板網(wǎng)！
