Changes report: Add ServerBaseUrlCustomizer functionality to be able to customize the generated Server URL. Fixes springdoc#1543.

Author: bnasslahsen

springdoc-openapi-starter-common/src/main/java/org/springdoc/core/configuration/SpringDocConfiguration.java

@@ -57,6 +57,7 @@
 import org.springdoc.core.customizers.OpenApiCustomizer;
 import org.springdoc.core.customizers.OperationCustomizer;
 import org.springdoc.core.customizers.PropertyCustomizer;
+import org.springdoc.core.customizers.ServerBaseUrlCustomizer;
 import org.springdoc.core.models.GroupedOpenApi;
 import org.springdoc.core.parsers.ReturnTypeParser;
 import org.springdoc.core.properties.SpringDocConfigProperties;
@@ -225,7 +226,7 @@ PolymorphicModelConverter polymorphicModelConverter() {
 	 * @param securityParser the security parser
 	 * @param springDocConfigProperties the spring doc config properties
 	 * @param propertyResolverUtils the property resolver utils
-	 * @param openApiBuilderCustomisers the open api builder customisers
+	 * @param openApiBuilderCustomizers the open api builder customisers
 	 * @return the open api builder
 	 */
 	@Bean
@@ -234,8 +235,9 @@ PolymorphicModelConverter polymorphicModelConverter() {
 	OpenAPIService openAPIBuilder(Optional<OpenAPI> openAPI,
 			SecurityService securityParser,
 			SpringDocConfigProperties springDocConfigProperties, PropertyResolverUtils propertyResolverUtils,
-			Optional<List<OpenApiBuilderCustomizer>> openApiBuilderCustomisers) {
-		return new OpenAPIService(openAPI, securityParser, springDocConfigProperties, propertyResolverUtils, openApiBuilderCustomisers);
+			Optional<List<OpenApiBuilderCustomizer>> openApiBuilderCustomizers,
+			Optional<List<ServerBaseUrlCustomizer>> serverBaseUrlCustomisers) {
+		return new OpenAPIService(openAPI, securityParser, springDocConfigProperties, propertyResolverUtils, openApiBuilderCustomizers, serverBaseUrlCustomisers);
 	}
 
 	/**

springdoc-openapi-starter-common/src/main/java/org/springdoc/core/customizers/ServerBaseUrlCustomizer.java

@@ -0,0 +1,17 @@
+package org.springdoc.core.customizers;
+
+/**
+ * The interface Server Base URL customiser.
+ * @author skylar-stark
+ */
+@FunctionalInterface
+public interface ServerBaseUrlCustomizer {
+
+	/**
+	 * Customise.
+	 * 
+	 * @param serverBaseUrl the serverBaseUrl.
+	 * @return the customised serverBaseUrl
+	 */
+	String customize(String serverBaseUrl);
+}

springdoc-openapi-starter-common/src/main/java/org/springdoc/core/service/OpenAPIService.java

@@ -65,6 +65,7 @@
 import org.slf4j.Logger;
 import org.slf4j.LoggerFactory;
 import org.springdoc.core.customizers.OpenApiBuilderCustomizer;
+import org.springdoc.core.customizers.ServerBaseUrlCustomizer;
 import org.springdoc.core.properties.SpringDocConfigProperties;
 import org.springdoc.core.utils.PropertyResolverUtils;
 
@@ -125,6 +126,11 @@ public class OpenAPIService implements ApplicationContextAware {
 	 */
 	private final Optional<List<OpenApiBuilderCustomizer>> openApiBuilderCustomisers;
 
+	/**
+	 * The server base URL customisers.
+	 */
+	private final Optional<List<ServerBaseUrlCustomizer>> serverBaseUrlCustomizers;
+
 	/**
 	 * The Spring doc config properties.
 	 */
@@ -189,11 +195,11 @@ public class OpenAPIService implements ApplicationContextAware {
 	 * @param securityParser the security parser
 	 * @param springDocConfigProperties the spring doc config properties
 	 * @param propertyResolverUtils the property resolver utils
-	 * @param openApiBuilderCustomisers the open api builder customisers
+	 * @param openApiBuilderCustomizers the open api builder customisers
 	 */
 	public OpenAPIService(Optional<OpenAPI> openAPI, SecurityService securityParser,
 			SpringDocConfigProperties springDocConfigProperties, PropertyResolverUtils propertyResolverUtils,
-			Optional<List<OpenApiBuilderCustomizer>> openApiBuilderCustomisers) {
+			Optional<List<OpenApiBuilderCustomizer>> openApiBuilderCustomizers, Optional<List<ServerBaseUrlCustomizer>> serverBaseUrlCustomizers) {
 		if (openAPI.isPresent()) {
 			this.openAPI = openAPI.get();
 			if (this.openAPI.getComponents() == null)
@@ -206,7 +212,8 @@ public OpenAPIService(Optional<OpenAPI> openAPI, SecurityService securityParser,
 		this.propertyResolverUtils=propertyResolverUtils;
 		this.securityParser = securityParser;
 		this.springDocConfigProperties = springDocConfigProperties;
-		this.openApiBuilderCustomisers = openApiBuilderCustomisers;
+		this.openApiBuilderCustomisers = openApiBuilderCustomizers;
+		this.serverBaseUrlCustomizers = serverBaseUrlCustomizers;
 		if (springDocConfigProperties.isUseFqn())
 			TypeNameResolver.std.setUseFqn(true);
 	}
@@ -472,7 +479,16 @@ public Schema resolveProperties(Schema schema, Locale locale) {
 	 * @param serverBaseUrl the server base url
 	 */
 	public void setServerBaseUrl(String serverBaseUrl) {
-		this.serverBaseUrl = serverBaseUrl;
+		String customServerBaseUrl = serverBaseUrl;
+
+		if (serverBaseUrlCustomizers != null && serverBaseUrlCustomizers.isPresent()) {
+			for (ServerBaseUrlCustomizer customiser : serverBaseUrlCustomizers.get()) {
+				customServerBaseUrl = customiser.customize(customServerBaseUrl);
+			}
+		}
+
+		this.serverBaseUrl = customServerBaseUrl;
+
 	}
 
 	/**

springdoc-openapi-starter-common/src/test/java/org/springdoc/api/AbstractOpenApiResourceTest.java

@@ -20,6 +20,7 @@
 
 package org.springdoc.api;
 
+import java.util.ArrayList;
 import java.util.HashMap;
 import java.util.List;
 import java.util.Locale;
@@ -43,6 +44,7 @@
 import org.mockito.junit.jupiter.MockitoExtension;
 import org.springdoc.core.customizers.OpenApiCustomizer;
 import org.springdoc.core.customizers.OperationCustomizer;
+import org.springdoc.core.customizers.ServerBaseUrlCustomizer;
 import org.springdoc.core.filters.OpenApiMethodFilter;
 import org.springdoc.core.fn.RouterOperation;
 import org.springdoc.core.properties.SpringDocConfigProperties;
@@ -68,6 +70,7 @@
 import static org.mockito.Mockito.when;
 import static org.springframework.web.bind.annotation.RequestMethod.GET;
 
+
 @ExtendWith(MockitoExtension.class)
 class AbstractOpenApiResourceTest {
 
@@ -111,6 +114,7 @@ public void setUp() {
 		openAPI = new OpenAPI();
 		openAPI.setPaths(new Paths().addPathItem(PATH, new PathItem()));
 		ReflectionTestUtils.setField(openAPIService, "cachedOpenAPI", new HashMap<>());
+		ReflectionTestUtils.setField(openAPIService, "serverBaseUrlCustomizers", Optional.empty());
 
 		when(openAPIService.getCalculatedOpenAPI()).thenReturn(openAPI);
 		when(openAPIService.getContext()).thenReturn(context);
@@ -187,7 +191,7 @@ void preLoadingModeShouldNotOverwriteServers() throws InterruptedException {
 
 		String customUrl = "https://custom.com";
 		String generatedUrl = "https://generated.com";
-		OpenApiCustomizer openApiCustomizer = openApi -> openApi.setServers(singletonList(new Server().url(customUrl)));
+		OpenApiCustomizer openApiCustomiser = openApi -> openApi.setServers(singletonList(new Server().url(customUrl)));
 		SpringDocConfigProperties properties = new SpringDocConfigProperties();
 		properties.setPreLoadingEnabled(true);
 
@@ -198,7 +202,7 @@ void preLoadingModeShouldNotOverwriteServers() throws InterruptedException {
 				responseBuilder,
 				operationParser,
 				Optional.empty(),
-				Optional.of(singletonList(openApiCustomizer)),
+				Optional.of(singletonList(openApiCustomiser)),
 				Optional.empty(),
 				properties, springDocProviders
 		);
@@ -215,6 +219,71 @@ void preLoadingModeShouldNotOverwriteServers() throws InterruptedException {
 		assertThat(after.getServers().get(0).getUrl(), is(customUrl));
 	}
 
+	@Test
+	void serverBaseUrlCustomisersTest() throws InterruptedException {
+		when(openAPIService.updateServers(any())).thenCallRealMethod();
+		when(openAPIService.getCachedOpenAPI(any())).thenCallRealMethod();
+		doAnswer(new CallsRealMethods()).when(openAPIService).setServerBaseUrl(any());
+		doAnswer(new CallsRealMethods()).when(openAPIService).setCachedOpenAPI(any(), any());
+
+		SpringDocConfigProperties properties = new SpringDocConfigProperties();
+		properties.setPreLoadingEnabled(true);
+
+		resource = new EmptyPathsOpenApiResource(
+				GROUP_NAME,
+				openAPIBuilderObjectFactory,
+				requestBuilder,
+				responseBuilder,
+				operationParser,
+				Optional.empty(),
+				Optional.empty(),
+				Optional.empty(),
+				properties,
+				springDocProviders
+		);
+
+		// wait for executor to be done
+		Thread.sleep(1_000);
+
+		Locale locale = Locale.US;
+
+		// Test that setting generated URL works fine with no customizers present
+		String generatedUrl = "https://generated-url.com/context-path";
+		openAPIService.setServerBaseUrl(generatedUrl);
+		openAPIService.updateServers(openAPI);
+		OpenAPI after = resource.getOpenApi(locale);
+		assertThat(after.getServers().get(0).getUrl(), is(generatedUrl));
+
+		// Test that adding a serverBaseUrlCustomizer has the desired effect
+		ServerBaseUrlCustomizer serverBaseUrlCustomizer = serverBaseUrl -> serverBaseUrl.replace("/context-path", "");
+		List<ServerBaseUrlCustomizer> serverBaseUrlCustomizerList = new ArrayList<>();
+		serverBaseUrlCustomizerList.add(serverBaseUrlCustomizer);
+
+		ReflectionTestUtils.setField(openAPIService, "serverBaseUrlCustomizers", Optional.of(serverBaseUrlCustomizerList));
+		openAPIService.setServerBaseUrl(generatedUrl);
+		openAPIService.updateServers(openAPI);
+		after = resource.getOpenApi(locale);
+		assertThat(after.getServers().get(0).getUrl(), is("https://generated-url.com"));
+
+		// Test that serverBaseUrlCustomisers are performed in order
+		generatedUrl = "https://generated-url.com/context-path/second-path";
+		ServerBaseUrlCustomizer serverBaseUrlCustomiser2 = serverBaseUrl -> serverBaseUrl.replace("/context-path/second-path", "");
+		serverBaseUrlCustomizerList.add(serverBaseUrlCustomiser2);
+
+		openAPIService.setServerBaseUrl(generatedUrl);
+		openAPIService.updateServers(openAPI);
+		after = resource.getOpenApi(locale);
+		assertThat(after.getServers().get(0).getUrl(), is("https://generated-url.com/second-path"));
+
+		// Test that all serverBaseUrlCustomisers in the List are performed
+		ServerBaseUrlCustomizer serverBaseUrlCustomiser3 = serverBaseUrl -> serverBaseUrl.replace("/second-path", "");
+		serverBaseUrlCustomizerList.add(serverBaseUrlCustomiser3);
+
+		openAPIService.setServerBaseUrl(generatedUrl);
+		openAPIService.updateServers(openAPI);
+		after = resource.getOpenApi(locale);
+		assertThat(after.getServers().get(0).getUrl(), is("https://generated-url.com"));
+	}
 
 	private static class EmptyPathsOpenApiResource extends AbstractOpenApiResource {