feat: add profile-aware endpoint for swagger/openapi URL

Agent-Logs-Url: https://github.com/conorheffron/ironoc/sessions/40192244-9ac4-4d16-9a96-7c8b085fdb31

Co-authored-by: conorheffron <8218626+conorheffron@users.noreply.github.com>

Author: Copilot

src/main/java/net/ironoc/portfolio/controller/VersionController.java

@@ -1,23 +1,35 @@
 package net.ironoc.portfolio.controller;
 
+import module java.base;
+
 import io.swagger.v3.oas.annotations.Operation;
 import io.swagger.v3.oas.annotations.responses.ApiResponse;
 import io.swagger.v3.oas.annotations.responses.ApiResponses;
+import jakarta.servlet.http.HttpServletRequest;
 import org.springframework.beans.factory.annotation.Autowired;
 import org.springframework.boot.info.BuildProperties;
+import org.springframework.core.env.Environment;
 import org.springframework.http.MediaType;
 import org.springframework.web.bind.annotation.GetMapping;
 import org.springframework.web.bind.annotation.RequestMapping;
 import org.springframework.web.bind.annotation.RestController;
+import org.springframework.web.servlet.support.ServletUriComponentsBuilder;
 
 @RestController
 @RequestMapping("/api")
 public class VersionController {
 
+    private static final String PROD_PROFILE = "prod";
+    private static final String OPEN_API_PATH = "/api-docs";
+    private static final String SWAGGER_UI_PATH = "/swagger-ui-ironoc.html";
+
     private final BuildProperties buildProperties;
+    private final Environment environment;
 
-    public VersionController(@Autowired BuildProperties buildProperties) {
+    public VersionController(@Autowired BuildProperties buildProperties,
+                             @Autowired Environment environment) {
         this.buildProperties = buildProperties;
+        this.environment = environment;
     }
 
     @Operation(summary = "Get ironoc Application Version",
@@ -30,4 +42,23 @@ public VersionController(@Autowired BuildProperties buildProperties) {
     public String getApplicationVersion() {
         return "Version: " + this.buildProperties.getVersion();
     }
+
+    @Operation(summary = "Get iRonoc API documentation endpoint",
+            description = "Returns the fully qualified Swagger/OpenAPI documentation URL based on the active run profile")
+    @ApiResponses(value = {
+            @ApiResponse(responseCode = "200",
+                    description = "Successfully retrieved iRonoc API documentation endpoint.")
+    })
+    @GetMapping(value = {"/application/openapi-endpoint"}, produces= MediaType.TEXT_PLAIN_VALUE)
+    public String getOpenApiDocumentationEndpoint(HttpServletRequest request) {
+        String endpointPath = isProdProfileActive() ? OPEN_API_PATH : SWAGGER_UI_PATH;
+        return ServletUriComponentsBuilder.fromContextPath(request)
+                .path(endpointPath)
+                .toUriString();
+    }
+
+    private boolean isProdProfileActive() {
+        return Arrays.stream(environment.getActiveProfiles())
+                .anyMatch(PROD_PROFILE::equalsIgnoreCase);
+    }
 }

src/test/java/net/ironoc/portfolio/controller/VersionControllerTest.java

@@ -8,6 +8,8 @@
 import org.mockito.Mock;
 import org.mockito.junit.jupiter.MockitoExtension;
 import org.springframework.boot.info.BuildProperties;
+import org.springframework.core.env.Environment;
+import org.springframework.mock.web.MockHttpServletRequest;
 
 import static org.hamcrest.MatcherAssert.assertThat;
 import static org.hamcrest.Matchers.is;
@@ -22,6 +24,9 @@ public class VersionControllerTest {
     @Mock
     private BuildProperties buildPropertiesMock;
 
+    @Mock
+    private Environment environmentMock;
+
     @InjectMocks
     private VersionController versionController;
 
@@ -38,4 +43,38 @@ public void test_getApplicationVersion_success() {
 
         assertThat(response, is("Version: " + TEST_VERSION));
     }
+
+    @Test
+    public void test_getOpenApiDocumentationEndpoint_nonProdProfile_success() {
+        // given
+        when(environmentMock.getActiveProfiles()).thenReturn(new String[]{"dev"});
+        MockHttpServletRequest request = new MockHttpServletRequest("GET", "/api/application/openapi-endpoint");
+        request.setScheme("http");
+        request.setServerName("localhost");
+        request.setServerPort(8080);
+
+        // when
+        String response = versionController.getOpenApiDocumentationEndpoint(request);
+
+        // then
+        verify(environmentMock).getActiveProfiles();
+        assertThat(response, is("http://localhost:8080/swagger-ui-ironoc.html"));
+    }
+
+    @Test
+    public void test_getOpenApiDocumentationEndpoint_prodProfile_success() {
+        // given
+        when(environmentMock.getActiveProfiles()).thenReturn(new String[]{"prod"});
+        MockHttpServletRequest request = new MockHttpServletRequest("GET", "/api/application/openapi-endpoint");
+        request.setScheme("https");
+        request.setServerName("ironoc.net");
+        request.setServerPort(443);
+
+        // when
+        String response = versionController.getOpenApiDocumentationEndpoint(request);
+
+        // then
+        verify(environmentMock).getActiveProfiles();
+        assertThat(response, is("https://ironoc.net/api-docs"));
+    }
 }