From 7010e8a0583c8b1b65b2b21b44dba145044a780b Mon Sep 17 00:00:00 2001
From: Tim <135014430+nagisa77@users.noreply.github.com>
Date: Tue, 9 Sep 2025 15:03:25 +0800
Subject: [PATCH] feat: allow configuring multiple openapi servers

---
 .../com/openisle/config/OpenApiConfig.java    | 24 ++++++++++++-------
 .../openisle/config/SpringDocProperties.java  | 20 ++++++++++++++++
 .../src/main/resources/application.properties |  5 +++-
 3 files changed, 39 insertions(+), 10 deletions(-)
 create mode 100644 backend/src/main/java/com/openisle/config/SpringDocProperties.java

diff --git a/backend/src/main/java/com/openisle/config/OpenApiConfig.java b/backend/src/main/java/com/openisle/config/OpenApiConfig.java
index cb9f185a9..aaccf2332 100644
--- a/backend/src/main/java/com/openisle/config/OpenApiConfig.java
+++ b/backend/src/main/java/com/openisle/config/OpenApiConfig.java
@@ -8,13 +8,18 @@ import io.swagger.v3.oas.models.security.SecurityScheme;
 import io.swagger.v3.oas.models.servers.Server;
 
 import java.util.List;
+import java.util.stream.Collectors;
+import lombok.RequiredArgsConstructor;
 import org.springframework.beans.factory.annotation.Value;
 import org.springframework.context.annotation.Bean;
 import org.springframework.context.annotation.Configuration;
 
 @Configuration
+@RequiredArgsConstructor
 public class OpenApiConfig {
 
+    private final SpringDocProperties springDocProperties;
+
     @Value("${springdoc.info.title}")
     private String title;
 
@@ -30,20 +35,21 @@ public class OpenApiConfig {
     @Value("${springdoc.info.header}")
     private String header;
 
-    @Value("${springdoc.api-docs.server-url}")
-    private String serverUrl;
-
     @Bean
     public OpenAPI openAPI() {
         SecurityScheme securityScheme = new SecurityScheme()
-			.type(SecurityScheme.Type.HTTP)
-			.scheme(scheme.toLowerCase())
-			.bearerFormat("JWT")
-			.in(SecurityScheme.In.HEADER)
-			.name(header);
+                        .type(SecurityScheme.Type.HTTP)
+                        .scheme(scheme.toLowerCase())
+                        .bearerFormat("JWT")
+                        .in(SecurityScheme.In.HEADER)
+                        .name(header);
+
+        List<Server> servers = springDocProperties.getServers().stream()
+                .map(s -> new Server().url(s.getUrl()).description(s.getDescription()))
+                .collect(Collectors.toList());
 
         return new OpenAPI()
-                .servers(List.of(new Server().url(serverUrl)))
+                .servers(servers)
                 .info(new Info()
                         .title(title)
                         .description(description)
diff --git a/backend/src/main/java/com/openisle/config/SpringDocProperties.java b/backend/src/main/java/com/openisle/config/SpringDocProperties.java
new file mode 100644
index 000000000..2c1ceb9e1
--- /dev/null
+++ b/backend/src/main/java/com/openisle/config/SpringDocProperties.java
@@ -0,0 +1,20 @@
+package com.openisle.config;
+
+import java.util.ArrayList;
+import java.util.List;
+import lombok.Data;
+import org.springframework.boot.context.properties.ConfigurationProperties;
+import org.springframework.stereotype.Component;
+
+@Data
+@Component
+@ConfigurationProperties(prefix = "springdoc.api-docs")
+public class SpringDocProperties {
+    private List<ServerConfig> servers = new ArrayList<>();
+
+    @Data
+    public static class ServerConfig {
+        private String url;
+        private String description;
+    }
+}
diff --git a/backend/src/main/resources/application.properties b/backend/src/main/resources/application.properties
index 92061a672..c17cc54c1 100644
--- a/backend/src/main/resources/application.properties
+++ b/backend/src/main/resources/application.properties
@@ -108,7 +108,10 @@ rabbitmq.sharding.enabled=true
 # see https://springdoc.org/#springdoc-openapi-core-properties
 springdoc.api-docs.path=/api/v3/api-docs
 springdoc.api-docs.enabled=true
-springdoc.api-docs.server-url=${WEBSITE_URL:https://www.open-isle.com}
+springdoc.api-docs.servers[0].url=${WEBSITE_URL:https://www.open-isle.com}
+springdoc.api-docs.servers[0].description=正式环境
+springdoc.api-docs.servers[1].url=https://www.staging.open-isle.com
+springdoc.api-docs.servers[1].description=预发环境
 springdoc.info.title=OpenIsle
 springdoc.info.description=OpenIsle Open API Documentation
 springdoc.info.version=0.0.1