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

為什麼要選 Swagger/OpenAPI？

Swagger，現(xiàn)在的 OpenAPI 規(guī)格 (OAS)，是領先的 API 文件標準。它的好處包括：

• 行業(yè)標準：被廣泛採用並得到豐富的工俱生態(tài)系統(tǒng)的支持。
• 互動式文件：產生使用者友善的文檔，讓開發(fā)人員直接探索和測試 API。
• 提高開發(fā)人員生產力： SDK 和伺服器存根程式碼產生等功能可加速 API 開發(fā)。
• 增強協(xié)作：為開發(fā)人員、測試人員和利害關係人提供對 API 功能的共同理解。
• 簡化的測試和調試： Swagger UI 包含一個用於驗證 API 回應的測試介面。
• 跨語言支援：跨不同技術堆疊無縫整合。
• 輕鬆整合： 與 Spring Boot 和 Micronaut 等流行框架簡單整合。
• 自動化友善：支援 API 生命週期管理的自動化。
• 具有企業(yè)選項的開源：作為具有企業(yè)選項的免費開源工具提供。

Spring Cloud Gateway：基礎

Spring Cloud Gateway 基於 Spring Framework 5、Spring Boot 2 和 Project Reactor 構建，可作為將請求路由和過濾到微服務的中心入口點。

Spring Cloud Gateway 的功能：

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

根據(jù)定義的路由評估客戶端請求。 符合的請求由網關 Web 處理程序處理，在請求代理之前和之後執(zhí)行前置和後置過濾器。

建立應用程式：

先決條件：

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

逐步實作：

第 1 步：建立 Micronaut 應用程式（工作、Perk、標籤服務）

使用 Micronaut Launcher（[連結到啟動器]）建立三個 Micronaut 應用程式：job-service、perk-service 和 tag-service。 選擇 Java 或 Kotlin、最新穩(wěn)定的 Micronaut 版本、Swagger UI 和 OpenAPI 作為功能。 使用 Gradle 或 Maven 作為建置工具。 每個服務都將有一個可存取的 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

（重複 perk-service 和 tag-service，相應地調整套件名稱）。

第 2 步：建立 Spring Boot API 閘道

使用Spring Initializr（[連結到Spring Initializr]）產生Spring Boot專案。 包含以下相依性：Spring Cloud Gateway、Spring Boot Actuator 和 Spring Web。

第 3 步：將 Swagger 整合到 API 閘道

將必要的 Springdoc 依賴項加入 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 並指定每個微服務的 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網關連接埠設定為8080：

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

第 4 步：執(zhí)行應用程式

啟動四個應用程式（三個 Micronaut 服務和 Spring Boot Gateway）。 網關的 Swagger UI 可透過 http://localhost:8080/webjars/swagger-ui/index.html 存取。

結論：

這種組合方法提供了強大且文件齊全的微服務架構。 Spring Cloud Gateway 有效地路由要求，而 Swagger 則提供集中式互動式 API 文件體驗。 此設定顯著提高了開發(fā)人員的工作效率和協(xié)作能力。請記得將佔位符 URL 替換為微服務 Swagger YAML 檔案的實際 URL。

以上是使用 Spring API Gateway 和 Micronaut 從 API 閘道聚合微服務和 Swagger UI的詳細內容。更多資訊請關注PHP中文網其他相關文章！