@ahmttyydn/java-integration 1.0.1

package/scalar-webmvc/src/main/java/com/scalar/maven/webmvc/ScalarWebMvcActuatorEndpoint.java

@@ -0,0 +1,97 @@
+package com.scalar.maven.webmvc;
+
+import com.scalar.maven.core.ScalarHtmlRenderer;
+import com.scalar.maven.core.ScalarProperties;
+import jakarta.servlet.http.HttpServletRequest;
+import org.springframework.beans.factory.ObjectProvider;
+import org.springframework.beans.factory.annotation.Autowired;
+import org.springframework.boot.actuate.endpoint.annotation.Endpoint;
+import org.springframework.boot.actuate.endpoint.annotation.ReadOperation;
+import org.springframework.boot.actuate.endpoint.web.annotation.WebEndpoint;
+import org.springframework.http.MediaType;
+import org.springframework.http.ResponseEntity;
+
+import java.io.IOException;
+
+/**
+ * Actuator endpoint for serving the Scalar API Reference interface in Spring WebMVC applications.
+ *
+ * <p>
+ * This endpoint provides access to the Scalar API Reference interface through
+ * Spring Boot Actuator endpoints. It serves the same HTML content as the
+ * regular ScalarWebMvcController but is accessible at the actuator path.
+ * </p>
+ *
+ * <p>
+ * The endpoint is only enabled when {@code scalar.actuatorEnabled=true} is set
+ * in the configuration properties.
+ * </p>
+ *
+ * <p>
+ * Access the endpoint at: {@code /actuator/scalar}
+ * </p>
+ */
+@Endpoint(id = "scalar")
+@WebEndpoint(id = "scalar")
+public class ScalarWebMvcActuatorEndpoint {
+
+    @Autowired
+    private ObjectProvider<SpringBootScalarProperties> propertiesProvider;
+
+    /**
+     * Serves the Scalar API Reference interface as an actuator endpoint.
+     *
+     * <p>
+     * This method returns the same HTML content as the regular ScalarWebMvcController
+     * but is accessible through the actuator endpoint system.
+     * </p>
+     *
+     * @param request the HTTP request
+     * @return a ResponseEntity containing the HTML content for the API Reference
+     * interface
+     * @throws IOException if the HTML template cannot be loaded
+     */
+    @ReadOperation(produces = MediaType.TEXT_HTML_VALUE)
+    public final ResponseEntity<String> scalarUi(HttpServletRequest request) throws IOException {
+        ScalarProperties properties = propertiesProvider.getObject();
+        ScalarProperties configuredProperties = configureProperties(properties, request);
+
+        String html = ScalarHtmlRenderer.render(configuredProperties);
+
+        return ResponseEntity.ok()
+                .contentType(MediaType.TEXT_HTML)
+                .body(html);
+    }
+
+    /**
+     * Serves the JavaScript bundle for the Scalar API Reference.
+     *
+     * <p>
+     * This endpoint returns the JavaScript file that powers the Scalar API
+     * Reference interface. The file is served with the appropriate MIME type.
+     * </p>
+     *
+     * @return a ResponseEntity containing the JavaScript bundle
+     * @throws IOException if the JavaScript file cannot be loaded
+     */
+    @ReadOperation(produces = "application/javascript")
+    public final ResponseEntity<byte[]> scalarJs() throws IOException {
+        byte[] jsContent = ScalarHtmlRenderer.getScalarJsContent();
+        return ResponseEntity.ok()
+                .contentType(MediaType.valueOf("application/javascript"))
+                .body(jsContent);
+    }
+
+    /**
+     * Hook method that allows subclasses to configure properties before rendering.
+     * Override this method to customize the ScalarProperties before they are
+     * converted to JSON and rendered.
+     *
+     * @param properties the properties to configure
+     * @param request    the HTTP request
+     * @return the configured properties
+     */
+    protected ScalarProperties configureProperties(ScalarProperties properties, HttpServletRequest request) {
+        return properties;
+    }
+}

package/scalar-webmvc/src/main/java/com/scalar/maven/webmvc/ScalarWebMvcAutoConfiguration.java

@@ -0,0 +1,63 @@
+package com.scalar.maven.webmvc;
+
+import org.springframework.boot.actuate.autoconfigure.endpoint.condition.ConditionalOnAvailableEndpoint;
+import org.springframework.boot.autoconfigure.condition.ConditionalOnClass;
+import org.springframework.boot.autoconfigure.condition.ConditionalOnMissingBean;
+import org.springframework.boot.autoconfigure.condition.ConditionalOnProperty;
+import org.springframework.boot.context.properties.EnableConfigurationProperties;
+import org.springframework.context.annotation.Bean;
+import org.springframework.context.annotation.Configuration;
+
+/**
+ * Auto-configuration for the Scalar API Reference integration in Spring WebMVC applications.
+ *
+ * <p>
+ * This class provides automatic configuration for the Scalar API Reference
+ * in Spring Boot WebMVC applications. It automatically creates the necessary beans
+ * when the scalar integration is enabled.
+ * </p>
+ *
+ * <p>
+ * The auto-configuration is conditional on the {@code scalar.enabled} property
+ * being set to {@code true} (which is the default).
+ * </p>
+ *
+ * <p>
+ * This configuration:
+ * </p>
+ * <ul>
+ * <li>Enables configuration properties via {@link SpringBootScalarProperties}</li>
+ * <li>Creates a {@link ScalarWebMvcController} bean for serving the API reference</li>
+ * <li>Creates a {@link ScalarWebMvcActuatorEndpoint} bean when actuator is enabled</li>
+ * </ul>
+ */
+@Configuration
+@EnableConfigurationProperties(SpringBootScalarProperties.class)
+@ConditionalOnProperty(prefix = "scalar", name = "enabled", havingValue = "true", matchIfMissing = true)
+public class ScalarWebMvcAutoConfiguration {
+
+    /**
+     * Creates a ScalarWebMvcController bean.
+     *
+     * @return a configured ScalarWebMvcController instance
+     */
+    @Bean
+    @ConditionalOnMissingBean(ScalarWebMvcController.class)
+    public ScalarWebMvcController scalarWebMvcController() {
+        return new ScalarWebMvcController();
+    }
+
+    /**
+     * Creates a ScalarWebMvcActuatorEndpoint bean when actuator support is enabled.
+     * This endpoint exposes the Scalar UI at /actuator/scalar.
+     *
+     * @return a configured ScalarWebMvcActuatorEndpoint instance
+     */
+    @Bean
+    @ConditionalOnProperty(prefix = "scalar", name = "actuatorEnabled", havingValue = "true")
+    @ConditionalOnClass(name = "org.springframework.boot.actuate.endpoint.annotation.Endpoint")
+    @ConditionalOnAvailableEndpoint(endpoint = ScalarWebMvcActuatorEndpoint.class)
+    public ScalarWebMvcActuatorEndpoint scalarWebMvcActuatorEndpoint() {
+        return new ScalarWebMvcActuatorEndpoint();
+    }
+}

package/scalar-webmvc/src/main/java/com/scalar/maven/webmvc/ScalarWebMvcController.java

@@ -0,0 +1,103 @@
+package com.scalar.maven.webmvc;
+
+import com.scalar.maven.core.ScalarConstants;
+import com.scalar.maven.core.ScalarHtmlRenderer;
+import com.scalar.maven.core.ScalarProperties;
+import jakarta.servlet.http.HttpServletRequest;
+import org.springframework.beans.factory.ObjectProvider;
+import org.springframework.beans.factory.annotation.Autowired;
+import org.springframework.boot.autoconfigure.condition.ConditionalOnMissingBean;
+import org.springframework.http.MediaType;
+import org.springframework.http.ResponseEntity;
+import org.springframework.web.bind.annotation.GetMapping;
+import org.springframework.web.bind.annotation.RestController;
+
+import java.io.IOException;
+
+/**
+ * REST controller for serving the Scalar API Reference interface in Spring WebMVC applications.
+ *
+ * <p>
+ * This controller provides endpoints for accessing the Scalar API Reference
+ * interface and the associated JavaScript bundle. It automatically configures
+ * the interface based on the provided {@link ScalarProperties}.
+ * </p>
+ *
+ * <p>
+ * The controller serves two main endpoints:
+ * </p>
+ * <ul>
+ * <li>{@code /scalar} (or custom path) - The main API Reference interface</li>
+ * <li>{@code /scalar/scalar.js} (or custom path) - The JavaScript bundle</li>
+ * </ul>
+ *
+ * <p>
+ * This controller can be extended to customize behavior by overriding the
+ * {@link #configureProperties(ScalarProperties, HttpServletRequest)} method.
+ * </p>
+ */
+@RestController
+@ConditionalOnMissingBean(ScalarWebMvcController.class)
+public class ScalarWebMvcController {
+
+    @Autowired
+    private ObjectProvider<SpringBootScalarProperties> propertiesProvider;
+
+    /**
+     * Serves the main API Reference interface.
+     *
+     * <p>
+     * This endpoint returns an HTML page that displays the Scalar API Reference
+     * interface. The page is configured with the OpenAPI specification URL from
+     * the properties.
+     * </p>
+     *
+     * @param request the HTTP request
+     * @return a ResponseEntity containing the HTML content for the API Reference
+     * interface
+     * @throws IOException if the HTML template cannot be loaded
+     */
+    @GetMapping("${scalar.path:/scalar}")
+    public final ResponseEntity<String> getDocs(HttpServletRequest request) throws IOException {
+        ScalarProperties properties = propertiesProvider.getObject();
+        ScalarProperties configuredProperties = configureProperties(properties, request);
+
+        String html = ScalarHtmlRenderer.render(configuredProperties);
+
+        return ResponseEntity.ok()
+                .contentType(MediaType.TEXT_HTML)
+                .body(html);
+    }
+
+    /**
+     * Serves the JavaScript bundle for the Scalar API Reference.
+     *
+     * <p>
+     * This endpoint returns the JavaScript file that powers the Scalar API
+     * Reference interface. The file is served with the appropriate MIME type.
+     * </p>
+     *
+     * @return a ResponseEntity containing the JavaScript bundle
+     * @throws IOException if the JavaScript file cannot be loaded
+     */
+    @GetMapping("${scalar.path:/scalar}/" + ScalarConstants.JS_FILENAME)
+    public final ResponseEntity<byte[]> getScalarJs() throws IOException {
+        byte[] jsContent = ScalarHtmlRenderer.getScalarJsContent();
+        return ResponseEntity.ok()
+                .contentType(MediaType.valueOf("application/javascript"))
+                .body(jsContent);
+    }
+
+    /**
+     * Hook method that allows subclasses to configure properties before rendering.
+     * Override this method to customize the ScalarProperties before they are
+     * converted to JSON and rendered.
+     *
+     * @param properties the properties to configure
+     * @param request    the HTTP request
+     * @return the configured properties
+     */
+    protected ScalarProperties configureProperties(ScalarProperties properties, HttpServletRequest request) {
+        return properties;
+    }
+}

package/scalar-webmvc/src/main/java/com/scalar/maven/webmvc/SpringBootScalarProperties.java

@@ -0,0 +1,43 @@
+package com.scalar.maven.webmvc;
+
+import com.scalar.maven.core.ScalarProperties;
+import org.springframework.boot.context.properties.ConfigurationProperties;
+import org.springframework.context.annotation.Scope;
+
+/**
+ * Spring Boot configuration properties wrapper for Scalar API Reference integration.
+ *
+ * <p>
+ * This class extends {@link ScalarProperties} and adds Spring Boot's
+ * {@link ConfigurationProperties} annotation to enable automatic property binding
+ * from Spring Boot configuration files (e.g., application.properties, application.yml).
+ * </p>
+ *
+ * <p>
+ * This wrapper allows the core {@link ScalarProperties} class to remain
+ * framework-agnostic while providing Spring Boot-specific functionality in the
+ * WebMVC integration module.
+ * </p>
+ *
+ * <p>
+ * Example usage in application.properties:
+ * </p>
+ *
+ * <pre>
+ * scalar.url=https://example.com/openapi.json
+ * scalar.path=/docs
+ * scalar.enabled=true
+ * scalar.showSidebar=true
+ * scalar.hideModels=false
+ * scalar.darkMode=true
+ * scalar.theme=default
+ * scalar.layout=modern
+ * </pre>
+ */
+@ConfigurationProperties(prefix = "scalar")
+@Scope("prototype")
+public class SpringBootScalarProperties extends ScalarProperties {
+    // All functionality is inherited from ScalarProperties
+    // This class only adds the @ConfigurationProperties annotation
+}
+

package/scalar-webmvc/src/main/resources/META-INF/spring/org.springframework.boot.autoconfigure.AutoConfiguration.imports

@@ -0,0 +1,2 @@
+com.scalar.maven.webmvc.ScalarWebMvcAutoConfiguration
+

package/scalar-webmvc/src/test/java/com/scalar/maven/webmvc/ScalarWebMvcActuatorEndpointTest.java

@@ -0,0 +1,128 @@
+package com.scalar.maven.webmvc;
+
+import jakarta.servlet.http.HttpServletRequest;
+import org.junit.jupiter.api.BeforeEach;
+import org.junit.jupiter.api.DisplayName;
+import org.junit.jupiter.api.Nested;
+import org.junit.jupiter.api.Test;
+import org.junit.jupiter.api.extension.ExtendWith;
+import org.mockito.Mock;
+import org.mockito.junit.jupiter.MockitoExtension;
+import org.springframework.beans.factory.ObjectProvider;
+import org.springframework.http.HttpStatus;
+import org.springframework.http.MediaType;
+import org.springframework.http.ResponseEntity;
+import org.springframework.test.util.ReflectionTestUtils;
+
+import static org.assertj.core.api.Assertions.assertThat;
+import static org.mockito.Mockito.lenient;
+import static org.mockito.Mockito.when;
+
+@ExtendWith(MockitoExtension.class)
+@DisplayName("ScalarWebMvcActuatorEndpoint")
+class ScalarWebMvcActuatorEndpointTest {
+
+    @Mock
+    private SpringBootScalarProperties properties;
+
+    @Mock
+    private ObjectProvider<SpringBootScalarProperties> propertiesProvider;
+
+    @Mock
+    private HttpServletRequest request;
+
+    private ScalarWebMvcActuatorEndpoint endpoint;
+
+    @BeforeEach
+    void setUp() {
+        lenient().when(propertiesProvider.getObject()).thenReturn(properties);
+        endpoint = new ScalarWebMvcActuatorEndpoint();
+        ReflectionTestUtils.setField(endpoint, "propertiesProvider", propertiesProvider);
+    }
+
+    @Nested
+    @DisplayName("Scalar UI Endpoint")
+    class ScalarUiEndpoint {
+
+        @Test
+        @DisplayName("should return HTML with default configuration")
+        void shouldReturnHtmlWithDefaultConfiguration() throws Exception {
+            // Given
+            when(properties.getUrl()).thenReturn("https://registry.scalar.com/@scalar/apis/galaxy?format=json");
+            when(properties.getPageTitle()).thenReturn("Scalar API Reference");
+            when(properties.getPath()).thenReturn("/scalar");
+
+            // When
+            ResponseEntity<String> response = endpoint.scalarUi(request);
+
+            // Then
+            assertThat(response)
+                    .isNotNull()
+                    .satisfies(resp -> {
+                        assertThat(resp.getStatusCode()).isEqualTo(HttpStatus.OK);
+                        assertThat(resp.getHeaders().getContentType()).isEqualTo(MediaType.TEXT_HTML);
+                    });
+
+            String html = response.getBody();
+            assertThat(html)
+                    .isNotNull()
+                    .contains("<!doctype html>")
+                    .contains("<title>Scalar API Reference</title>")
+                    .contains("Scalar.createApiReference('#app',");
+        }
+
+        @Test
+        @DisplayName("should return HTML with custom URL")
+        void shouldReturnHtmlWithCustomUrl() throws Exception {
+            // Given
+            when(properties.getUrl()).thenReturn("https://example.com/api/openapi.json");
+            when(properties.getPageTitle()).thenReturn("Scalar API Reference");
+            when(properties.getPath()).thenReturn("/scalar");
+
+            // When
+            ResponseEntity<String> response = endpoint.scalarUi(request);
+
+            // Then
+            assertThat(response)
+                    .isNotNull()
+                    .satisfies(resp -> {
+                        assertThat(resp.getStatusCode()).isEqualTo(HttpStatus.OK);
+                        assertThat(resp.getHeaders().getContentType()).isEqualTo(MediaType.TEXT_HTML);
+                    });
+
+            String html = response.getBody();
+            assertThat(html)
+                    .isNotNull()
+                    .contains("<!doctype html>")
+                    .contains("<title>Scalar API Reference</title>")
+                    .contains("Scalar.createApiReference('#app',");
+        }
+    }
+
+    @Nested
+    @DisplayName("JavaScript Endpoint")
+    class JavaScriptEndpoint {
+
+        @Test
+        @DisplayName("should return JavaScript file with correct content type")
+        void shouldReturnJavaScriptFileWithCorrectContentType() throws Exception {
+            // When
+            ResponseEntity<byte[]> response = endpoint.scalarJs();
+
+            // Then
+            assertThat(response)
+                    .isNotNull()
+                    .satisfies(resp -> {
+                        assertThat(resp.getStatusCode()).isEqualTo(HttpStatus.OK);
+                        assertThat(resp.getHeaders().getContentType())
+                                .isEqualTo(MediaType.valueOf("application/javascript"));
+                    });
+
+            byte[] body = response.getBody();
+            assertThat(body)
+                    .isNotNull()
+                    .isNotEmpty();
+        }
+    }
+}
+

package/scalar-webmvc/src/test/java/com/scalar/maven/webmvc/ScalarWebMvcControllerTest.java

@@ -0,0 +1,154 @@
+package com.scalar.maven.webmvc;
+
+import jakarta.servlet.http.HttpServletRequest;
+import org.junit.jupiter.api.BeforeEach;
+import org.junit.jupiter.api.DisplayName;
+import org.junit.jupiter.api.Nested;
+import org.junit.jupiter.api.Test;
+import org.junit.jupiter.api.extension.ExtendWith;
+import org.mockito.Mock;
+import org.mockito.junit.jupiter.MockitoExtension;
+import org.springframework.beans.factory.ObjectProvider;
+import org.springframework.http.HttpStatus;
+import org.springframework.http.MediaType;
+import org.springframework.http.ResponseEntity;
+import org.springframework.test.util.ReflectionTestUtils;
+
+import static org.assertj.core.api.Assertions.assertThat;
+import static org.mockito.Mockito.lenient;
+import static org.mockito.Mockito.when;
+
+@ExtendWith(MockitoExtension.class)
+@DisplayName("ScalarWebMvcController")
+class ScalarWebMvcControllerTest {
+
+    @Mock
+    private SpringBootScalarProperties properties;
+
+    @Mock
+    private ObjectProvider<SpringBootScalarProperties> propertiesProvider;
+
+    @Mock
+    private HttpServletRequest request;
+
+    private ScalarWebMvcController controller;
+
+    @BeforeEach
+    void setUp() {
+        lenient().when(propertiesProvider.getObject()).thenReturn(properties);
+        controller = new ScalarWebMvcController();
+        ReflectionTestUtils.setField(controller, "propertiesProvider", propertiesProvider);
+    }
+
+    @Nested
+    @DisplayName("GET /scalar endpoint")
+    class GetDocsEndpoint {
+
+        @Test
+        @DisplayName("should return HTML with default configuration")
+        void shouldReturnHtmlWithDefaultConfiguration() throws Exception {
+            // Given
+            when(properties.getUrl()).thenReturn("https://registry.scalar.com/@scalar/apis/galaxy?format=json");
+            when(properties.getPageTitle()).thenReturn("Scalar API Reference");
+            when(properties.getPath()).thenReturn("/scalar");
+
+            // When
+            ResponseEntity<String> response = controller.getDocs(request);
+
+            // Then
+            assertThat(response)
+                    .isNotNull()
+                    .satisfies(resp -> {
+                        assertThat(resp.getStatusCode()).isEqualTo(HttpStatus.OK);
+                        assertThat(resp.getHeaders().getContentType()).isEqualTo(MediaType.TEXT_HTML);
+                    });
+
+            String html = response.getBody();
+            assertThat(html)
+                    .isNotNull()
+                    .contains("<!doctype html>")
+                    .contains("<title>Scalar API Reference</title>")
+                    .contains("Scalar.createApiReference('#app',");
+        }
+
+        @Test
+        @DisplayName("should return HTML with custom URL")
+        void shouldReturnHtmlWithCustomUrl() throws Exception {
+            // Given
+            when(properties.getUrl()).thenReturn("https://example.com/api/openapi.json");
+            when(properties.getPageTitle()).thenReturn("Scalar API Reference");
+            when(properties.getPath()).thenReturn("/scalar");
+
+            // When
+            ResponseEntity<String> response = controller.getDocs(request);
+
+            // Then
+            assertThat(response)
+                    .isNotNull()
+                    .satisfies(resp -> {
+                        assertThat(resp.getStatusCode()).isEqualTo(HttpStatus.OK);
+                        assertThat(resp.getHeaders().getContentType()).isEqualTo(MediaType.TEXT_HTML);
+                    });
+
+            String html = response.getBody();
+            assertThat(html)
+                    .isNotNull()
+                    .contains("<!doctype html>")
+                    .contains("<title>Scalar API Reference</title>")
+                    .contains("Scalar.createApiReference('#app',");
+        }
+
+        @Test
+        @DisplayName("should return HTML with custom pageTitle")
+        void shouldReturnHtmlWithCustomPageTitle() throws Exception {
+            // Given
+            when(properties.getPageTitle()).thenReturn("My Custom API Documentation");
+            when(properties.getPath()).thenReturn("/scalar");
+
+            // When
+            ResponseEntity<String> response = controller.getDocs(request);
+
+            // Then
+            assertThat(response)
+                    .isNotNull()
+                    .satisfies(resp -> {
+                        assertThat(resp.getStatusCode()).isEqualTo(HttpStatus.OK);
+                        assertThat(resp.getHeaders().getContentType()).isEqualTo(MediaType.TEXT_HTML);
+                    });
+
+            String html = response.getBody();
+            assertThat(html)
+                    .isNotNull()
+                    .contains("<!doctype html>")
+                    .contains("<title>My Custom API Documentation</title>")
+                    .contains("Scalar.createApiReference('#app',");
+        }
+    }
+
+    @Nested
+    @DisplayName("GET /scalar/scalar.js endpoint")
+    class GetScalarJsEndpoint {
+
+        @Test
+        @DisplayName("should return JavaScript file with correct content type")
+        void shouldReturnJavaScriptFileWithCorrectContentType() throws Exception {
+            // When
+            ResponseEntity<byte[]> response = controller.getScalarJs();
+
+            // Then
+            assertThat(response)
+                    .isNotNull()
+                    .satisfies(resp -> {
+                        assertThat(resp.getStatusCode()).isEqualTo(HttpStatus.OK);
+                        assertThat(resp.getHeaders().getContentType())
+                                .isEqualTo(MediaType.valueOf("application/javascript"));
+                    });
+
+            byte[] body = response.getBody();
+            assertThat(body)
+                    .isNotNull()
+                    .isNotEmpty();
+        }
+    }
+}
+