本指南示範(fàn)了將 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)的支持。
• 互動(dòng)式文件：產(chǎn)生使用者友善的文檔，讓開發(fā)人員直接探索和測試 API。
• 提高開發(fā)人員生產(chǎn)力： SDK 和伺服器存根程式碼產(chǎn)生等功能可加速 API 開發(fā)。
• 增強(qiáng)協(xié)作：為開發(fā)人員、測試人員和利害關(guān)係人提供對(duì) 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)建，可作為將請求路由和過濾到微服務(wù)的中心入口點(diǎn)。

Spring Cloud Gateway 的功能：

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

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

建立應(yīng)用程式：

先決條件：

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

逐步實(shí)作：

第 1 步：建立 Micronaut 應(yīng)用程式（工作、Perk、標(biāo)籤服務(wù)）

使用 Micronaut Launcher（[連結(jié)到啟動(dòng)器]）建立三個(gè) Micronaut 應(yīng)用程式：job-service、perk-service 和 tag-service。 選擇 Java 或 Kotlin、最新穩(wěn)定的 Micronaut 版本、Swagger UI 和 OpenAPI 作為功能。 使用 Gradle 或 Maven 作為建置工具。 每個(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

（重複 perk-service 和 tag-service，相應(yīng)地調(diào)整套件名稱）。

第 2 步：建立 Spring Boot API 閘道

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

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

將必要的 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")
}

設(shè)定 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 步：執(zhí)行應(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 則提供集中式互動(dòng)式 API 文件體驗(yàn)。 此設(shè)定顯著提高了開發(fā)人員的工作效率和協(xié)作能力。請記得將佔(zhàn)位符 URL 替換為微服務(wù) Swagger YAML 檔案的實(shí)際 URL。

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