知識庫 / Spring / Spring Cloud RSS 訂閱

1. 概述

文檔是構建任何健壯的 REST API 的關鍵組成部分。我們可以基於 OpenAPI 規範實現 API 文檔，並在 Spring 應用中使用 Swagger UI 進行可視化。

此外，API 端點可以使用 API 網關進行暴露，因此我們也需要將後端服務的 OpenAPI 文檔與網關服務集成。網關服務將提供所有 API 文檔的集中視圖。

在本文中，我們將學習如何在 Spring 應用中集成 OpenAPI，並使用 Spring Cloud Gateway 服務來暴露後端服務的 API 文檔。

2. 示例應用程序

讓我們假設我們需要構建一個簡單的微服務來獲取一些數據。

2.1 Maven 依賴

首先，我們將包含 spring-boot-starter-web 依賴：

<dependency>
    <groupId>org.springframework.boot</groupId>
    <artifactId>spring-boot-starter-web</artifactId>
    <version>3.3.2</version>
</dependency>

2.2. 實現 REST API

我們的後端應用程序將具有一個端點，用於返回 Product 數據。

首先，讓我們對 Product 類進行建模：

public class Product {
    private long id;
    private String name;
    //standard getters and setters
}

接下來，我們將實現 ProductController 及其 getProduct 端點：

@GetMapping(path = "/product/{id}")
public Product getProduct(@PathVariable("id") long productId){
    LOGGER.info("Getting Product Details for Product Id {}", productId);
    return productMap.get(productId);
}

3. 將 Spring 應用與 OpenAPI 集成

OpenAPI 3.0 規範可以通過使用 springdoc-openapi 啓動器項目，與 Spring Boot 3 集成。

3.1. Springdoc 依賴

Spring Boot 3.x 要求我們使用 版本 2 的 springdoc-openapi-starter-webmvc-ui 依賴：

<dependency>
    <groupId>org.springdoc</groupId>
    <artifactId>springdoc-openapi-starter-webmvc-ui</artifactId>
    <version>2.6.0</version>
</dependency>

3.2. 配置 OpenAPI 定義

我們可以通過使用少量 Swagger 註解來定製 OpenAPI 定義的細節，例如標題、描述和版本。

我們將配置 @OpenAPI Bean，並設置 @OpenAPIDefinition 註解：

@OpenAPIDefinition
@Configuration
public class OpenAPIConfig {

    @Bean
    public OpenAPI customOpenAPI() {
        return new OpenAPI()
          .servers(List.of(new Server().url("http://localhost:8080")))
          .info(new Info().title("Product Service API").version("1.0.0"));
    }
}

3.3. 配置 OpenAPI 和 Swagger UI 路徑

OpenAPI 和 Swagger UI 的默認路徑可以通過 springdoc-openapi 配置進行自定義。

我們將 Product 相關的路徑包含在 springdoc-openapi 的屬性中：

springdoc:
  api-docs:
    enabled: true 
    path: /product/v3/api-docs
  swagger-ui:
    enabled: true
    path: /product/swagger-ui.html

我們可以通過將 OpenAPI 的 api-docs 和 Swagger UI 功能的 enabled 標誌設置為 false，在任何環境中禁用這些功能：

springdoc:
  api-docs:
    enabled: false
  swagger-ui:
    enabled: false

@Operation(summary = "Get a product by its id")
    @ApiResponses(value = {
      @ApiResponse(responseCode = "200", description = "Found the product",
        content = { @Content(mediaType = "application/json", 
          schema = @Schema(implementation = Product.class)) }),
      @ApiResponse(responseCode = "400", description = "Invalid id supplied",
        content = @Content),
      @ApiResponse(responseCode = "404", description = "Product not found",
        content = @Content) })
@GetMapping(path = "/product/{id}")
public Product getProduct(@Parameter(description = "id of product to be searched") 
  @PathVariable("id") long productId){

<dependency>
    <groupId>org.springframework.cloud</groupId>
    <artifactId>spring-cloud-starter-gateway</artifactId>
    <version>4.1.5</version
</dependency>

spring:
  cloud:
    gateway:
      routes:
        -   id: product_service_route
            predicates:
              - Path=/product/**
            uri: http://localhost:8081

$ java -jar ./spring-backend-service/target/spring-backend-service-1.0.0-SNAPSHOT.jar

$ java -jar ./spring-cloud-gateway-service/target/spring-cloud-gateway-service-1.0.0-SNAPSHOT.jar

$ curl -v 'http://localhost:8080/product/100001'

< HTTP/1.1 200 OK
< Content-Type: application/json
{"id":100001,"name":"Apple"}

<dependency>
    <groupId>org.springdoc</groupId>
    <artifactId>springdoc-openapi-starter-webflux-ui</artifactId>
    <version>2.6.0</version>
</dependency>

@OpenAPIDefinition
@Configuration
public class OpenAPIConfig {

    @Bean
    public OpenAPI customOpenAPI() {
        return new OpenAPI().info(new Info()
          .title("API Gateway Service")
          .description("API Gateway Service")
          .version("1.0.0"));
    }
}

springdoc:
  api-docs:
    enabled: true
    path: /v3/api-docs
  swagger-ui:
    enabled: true
    config-url: /v3/api-docs/swagger-config
    urls:
      -   name: gateway-service
          url: /v3/api-docs

springdoc:
  swagger-ui:
    urls:
      -   name: gateway-service
          url: /v3/api-docs
      -   name: product-service
          url: /product/v3/api-docs