本指南演示了將 Swagger 3 (OpenAPI) 與 Spring Cloud Gateway 集成以簡化微服務(wù) API 文檔。 我們將利用 Java 21、Spring Boot 3.2 和 Micronaut 來創(chuàng)建強(qiáng)大且用戶友好的解決方案。

為什么選擇 Swagger/OpenAPI？

Swagger，現(xiàn)在的 OpenAPI 規(guī)范 (OAS)，是領(lǐng)先的 API 文檔標(biāo)準(zhǔn)。它的好處包括：

• 行業(yè)標(biāo)準(zhǔn)：被廣泛采用并得到豐富的工具生態(tài)系統(tǒng)的支持。
• 交互式文檔：生成用戶友好的文檔，允許開發(fā)人員直接探索和測試 API。
• 提高開發(fā)人員生產(chǎn)力： SDK 和服務(wù)器存根代碼生成等功能可加速 API 開發(fā)。
• 增強(qiáng)協(xié)作：為開發(fā)人員、測試人員和利益相關(guān)者提供對 API 功能的共同理解。
• 簡化的測試和調(diào)試： Swagger UI 包含一個(gè)用于驗(yàn)證 API 響應(yīng)的測試接口。
• 跨語言支持：跨不同技術(shù)堆棧無縫集成。
• 輕松集成： 與 Spring Boot 和 Micronaut 等流行框架簡單集成。
• 自動(dòng)化友好：支持 API 生命周期管理的自動(dòng)化。
• 具有企業(yè)選項(xiàng)的開源：作為具有企業(yè)選項(xiàng)的免費(fèi)開源工具提供。

Spring Cloud Gateway：基礎(chǔ)

Spring Cloud Gateway 基于 Spring Framework 5、Spring Boot 2 和 Project Reactor 構(gòu)建，充當(dāng)將請求路由和過濾到微服務(wù)的中心入口點(diǎn)。

Spring Cloud Gateway 的功能：

下圖說明了 Spring Cloud Gateway 的操作：

根據(jù)定義的路由評(píng)估客戶端請求。 匹配的請求由網(wǎng)關(guān) Web 處理程序處理，在請求代理之前和之后執(zhí)行前置和后置過濾器。

構(gòu)建應(yīng)用程序：

先決條件：

1. Java 21
2. Gradle（或 Maven）
3. Spring Boot 3.2 或更高版本
4. Spring Cloud Gateway 和 Swagger 的理解
5. 微型機(jī)器人

逐步實(shí)施：

第 1 步：創(chuàng)建 Micronaut 應(yīng)用程序（工作、Perk、標(biāo)簽服務(wù)）

使用 Micronaut Launcher（[鏈接到啟動(dòng)器]）創(chuàng)建三個(gè) Micronaut 應(yīng)用程序：job-service、perk-service 和 tag-service。 選擇 Java 或 Kotlin、最新穩(wěn)定的 Micronaut 版本、Swagger UI 和 OpenAPI 作為功能。 使用 Gradle 或 Maven 作為構(gòu)建工具。 每個(gè)服務(wù)都將有一個(gè)可訪問的 Swagger UI（例如，http://localhost:8081/swagger-ui/index.html 代表 job-service）。 您還可以使用 CLI：

mn create-app --build=gradle_kotlin --jdk=21 --lang=java --test=junit --features=openapi,swagger-ui dev.job.job

（重復(fù) perk-service 和 tag-service，相應(yīng)地調(diào)整包名稱）。

第 2 步：創(chuàng)建 Spring Boot API 網(wǎng)關(guān)

使用Spring Initializr（[鏈接到Spring Initializr]）生成Spring Boot項(xiàng)目。 包含以下依賴項(xiàng)：Spring Cloud Gateway、Spring Boot Actuator 和 Spring Web。

第 3 步：將 Swagger 集成到 API 網(wǎng)關(guān)

將必要的 Springdoc 依賴項(xiàng)添加到 pom.xml (Maven) 或 build.gradle (Gradle)：

dependencies {
    implementation("org.springframework.cloud:spring-cloud-starter-gateway")
    implementation("org.springdoc:springdoc-openapi-starter-webmvc-api:2.8.3")
    implementation("org.springdoc:springdoc-openapi-starter-webflux-ui:2.8.3")
}

配置 application.yml 以啟用 Swagger UI 并指定每個(gè)微服務(wù)的 Swagger YAML 文件的 URL：

springdoc:
  api-docs:
    enabled: true
  swagger-ui:
    enabled: true
    path: /swagger-ui.html
    config-url: /v3/api-docs/swagger-config
    urls:
      - name: Job Service
        url: http://localhost:8081/swagger/job-service-0.0.yml
      - name: Perk Service
        url: http://localhost:8082/swagger/perk-0.0.yml
      - name: Tag Service
        url: http://localhost:8083/swagger/tag-0.0.yml

在application.yml中將API網(wǎng)關(guān)端口設(shè)置為8080：

server:
  port: 8080
spring:
  application:
    name: web-api-gateway

第 4 步：運(yùn)行應(yīng)用程序

啟動(dòng)四個(gè)應(yīng)用程序（三個(gè) Micronaut 服務(wù)和 Spring Boot Gateway）。 網(wǎng)關(guān)的 Swagger UI 可通過 http://localhost:8080/webjars/swagger-ui/index.html 訪問。

結(jié)論：

這種組合方法提供了強(qiáng)大且文檔齊全的微服務(wù)架構(gòu)。 Spring Cloud Gateway 有效地路由請求，而 Swagger 則提供集中式交互式 API 文檔體驗(yàn)。 此設(shè)置顯著提高了開發(fā)人員的工作效率和協(xié)作能力。請記住將占位符 URL 替換為微服務(wù) Swagger YAML 文件的實(shí)際 URL。

以上是使用 Spring API Gateway 和 Micronaut 從 API 網(wǎng)關(guān)聚合微服務(wù)和 Swagger UI的詳細(xì)內(nèi)容。更多信息請關(guān)注PHP中文網(wǎng)其他相關(guān)文章！