@ahmttyydn/java-integration 1.0.1

package/README.md

@@ -0,0 +1,37 @@
+<!--
+  This file is auto-generated by the Scalar README generator.
+  Command: pnpm --filter @scalar-internal/build-scripts start generate-readme
+  
+  Do not edit this file manually. Changes will be lost when the file is regenerated.
+-->
+
+# Scalar API Reference for Java
+
+[![Version](https://img.shields.io/maven-central/v/com.scalar.maven/scalar-core.svg)](https://central.sonatype.com/artifact/com.scalar.maven/scalar-core)
+[![Discord](https://img.shields.io/discord/1135330207960678410?style=flat&color=5865F2)](https://discord.gg/scalar)
+
+Scalar API Reference Java integrations for Spring Boot
+
+## Documentation
+
+[Read the documentation here](https://scalar.com/products/api-references/integrations/java)
+
+### Available Packages
+
+This integration provides three Maven packages:
+
+- `com.scalar.maven:scalar-core` - Core framework-agnostic module for Scalar API Reference
+- `com.scalar.maven:scalar-webmvc` - Spring Boot WebMVC integration for Scalar API Reference
+- `com.scalar.maven:scalar-webflux` - Spring Boot WebFlux integration for Scalar API Reference
+
+## Changelog
+
+See [CHANGELOG.md](https://github.com/scalar/scalar/blob/main/integrations/java/CHANGELOG.md) for a list of changes.
+
+## Community
+
+We are API nerds. You too? Let’s chat on Discord: <https://discord.gg/scalar>
+
+## License
+
+The source code in this repository is licensed under [MIT](https://github.com/scalar/scalar/blob/main/LICENSE).

package/package.json

@@ -0,0 +1,46 @@
+{
+  "name": "@ahmttyydn/java-integration",
+  "description": "Scalar API Reference Java integrations for Spring Boot",
+  "license": "MIT",
+  "author": "Scalar (https://github.com/scalar)",
+  "homepage": "https://github.com/scalar/scalar",
+  "bugs": "https://github.com/scalar/scalar/issues/new/choose",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/scalar/scalar.git",
+    "directory": "integrations/java"
+  },
+  "version": "1.0.1",
+  "private": false,
+  "engines": {
+    "node": ">=22"
+  },
+  "scripts": {
+    "build": "command -v mvn >/dev/null 2>&1 && pnpm copy:standalone && mvn clean package -Dgpg.skip=true || echo '⚠️ Maven is not available or the build failed, ignoring it.'",
+    "copy:standalone": "shx cp ../../packages/api-reference/dist/browser/standalone.js ./scalar-core/src/main/resources/META-INF/resources/webjars/scalar/scalar.js",
+    "mvn:install": "command -v mvn >/dev/null 2>&1 && pnpm copy:standalone && mvn clean install -Dgpg.skip=true || echo '⚠️ Maven is not available or the build failed, ignoring it.'",
+    "mvn:run:webflux": "cd scalar-playground-webflux && mvn spring-boot:run",
+    "mvn:run:webmvc": "cd scalar-playground-webmvc && mvn spring-boot:run",
+    "update:version": "mvn versions:set -DnewVersion=$npm_package_version -DgenerateBackupPoms=false"
+  },
+  "readme": {
+    "title": "Scalar API Reference for Java",
+    "badges": [
+      {
+        "type": "maven-central-version",
+        "package": "com.scalar.maven/scalar-core"
+      }
+    ],
+    "documentation": "https://scalar.com/products/api-references/integrations/java",
+    "extraContent": {
+      "headline": "Available Packages",
+      "content": "This integration provides three Maven packages:\n\n- `com.scalar.maven:scalar-core` - Core framework-agnostic module for Scalar API Reference\n- `com.scalar.maven:scalar-webmvc` - Spring Boot WebMVC integration for Scalar API Reference\n- `com.scalar.maven:scalar-webflux` - Spring Boot WebFlux integration for Scalar API Reference"
+    }
+  },
+  "dependencies": {
+    "@ahmttyydn/api-reference": "workspace:*"
+  },
+  "devDependencies": {
+    "@ahmttyydn/snippetz": "workspace:*"
+  }
+}

package/pom.xml

@@ -0,0 +1,242 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<project xmlns="http://maven.apache.org/POM/4.0.0"
+         xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
+         xsi:schemaLocation="http://maven.apache.org/POM/4.0.0
+         http://maven.apache.org/xsd/maven-4.0.0.xsd">
+  <modelVersion>4.0.0</modelVersion>
+
+  <!-- Don't touch this, this is our verified namespace in the Maven Central Repository. -->
+  <groupId>com.scalar.maven</groupId>
+  <artifactId>scalar-parent</artifactId>
+  <!-- This will replaced with the version from the package.json right before release. -->
+  <!-- Just keep it 0.0.0, don't touch it. -->
+  <version>0.0.0</version>
+  <packaging>pom</packaging>
+
+  <name>Scalar API Reference Parent</name>
+  <description>Parent POM for Scalar API Reference Java integrations</description>
+  <url>https://github.com/scalar/scalar</url>
+
+  <licenses>
+    <license>
+      <name>MIT License</name>
+      <url>https://opensource.org/licenses/MIT</url>
+      <distribution>repo</distribution>
+    </license>
+  </licenses>
+
+  <developers>
+    <developer>
+      <id>scalar</id>
+      <!-- Don't touch this, it needs to match the GPG Key (Scalar <support@scalar.com>) -->
+      <name>Scalar</name>
+      <!-- Don't touch this, it needs to match the GPG Key (Scalar <support@scalar.com>) -->
+      <email>support@scalar.com</email>
+    </developer>
+  </developers>
+
+  <scm>
+    <url>https://github.com/scalar/scalar</url>
+    <connection>scm:git:https://github.com/scalar/scalar.git</connection>
+    <developerConnection>scm:git:git@github.com/scalar/scalar.git</developerConnection>
+  </scm>
+
+  <distributionManagement>
+    <repository>
+      <id>central</id>
+      <name>Maven Central Release Repository</name>
+      <url>https://central.sonatype.com/api/v1/publish</url>
+    </repository>
+  </distributionManagement>
+
+  <modules>
+    <module>scalar-core</module>
+    <module>scalar-webmvc</module>
+    <module>scalar-webflux</module>
+    <module>scalar-playground-webmvc</module>
+    <module>scalar-playground-webflux</module>
+  </modules>
+
+  <properties>
+    <java.version>17</java.version>
+    <maven.compiler.release>17</maven.compiler.release>
+    <project.build.sourceEncoding>UTF-8</project.build.sourceEncoding>
+    <gpg.skip>false</gpg.skip>
+  </properties>
+
+  <dependencyManagement>
+    <dependencies>
+      <!-- Spring Boot BOM -->
+      <dependency>
+        <groupId>org.springframework.boot</groupId>
+        <artifactId>spring-boot-dependencies</artifactId>
+        <version>3.5.7</version>
+        <type>pom</type>
+        <scope>import</scope>
+      </dependency>
+    </dependencies>
+  </dependencyManagement>
+
+  <build>
+    <pluginManagement>
+      <plugins>
+        <!-- Maven Compiler Plugin -->
+        <plugin>
+          <groupId>org.apache.maven.plugins</groupId>
+          <artifactId>maven-compiler-plugin</artifactId>
+          <version>3.15.0</version>
+          <configuration>
+            <release>17</release>
+            <encoding>UTF-8</encoding>
+          </configuration>
+        </plugin>
+
+        <!-- Surefire plugin for running tests -->
+        <plugin>
+          <groupId>org.apache.maven.plugins</groupId>
+          <artifactId>maven-surefire-plugin</artifactId>
+          <version>3.5.5</version>
+          <configuration>
+            <argLine>-XX:+EnableDynamicAgentLoading</argLine>
+          </configuration>
+        </plugin>
+
+        <!-- Source JAR -->
+        <plugin>
+          <groupId>org.apache.maven.plugins</groupId>
+          <artifactId>maven-source-plugin</artifactId>
+          <version>3.4.0</version>
+          <executions>
+            <execution>
+              <id>attach-sources</id>
+              <phase>verify</phase>
+              <goals>
+                <goal>jar</goal>
+              </goals>
+            </execution>
+          </executions>
+        </plugin>
+
+        <!-- Javadoc JAR -->
+        <plugin>
+          <groupId>org.apache.maven.plugins</groupId>
+          <artifactId>maven-javadoc-plugin</artifactId>
+          <version>3.12.0</version>
+          <executions>
+            <execution>
+              <id>generate-javadoc</id>
+              <phase>compile</phase>
+              <goals>
+                <goal>javadoc</goal>
+              </goals>
+            </execution>
+            <execution>
+              <id>attach-javadocs</id>
+              <phase>verify</phase>
+              <goals>
+                <goal>jar</goal>
+              </goals>
+            </execution>
+          </executions>
+          <configuration>
+            <release>17</release>
+            <encoding>UTF-8</encoding>
+            <doclint>none</doclint>
+            <failOnError>true</failOnError>
+          </configuration>
+        </plugin>
+
+        <!-- GPG Signing -->
+        <plugin>
+          <groupId>org.apache.maven.plugins</groupId>
+          <artifactId>maven-gpg-plugin</artifactId>
+          <version>3.2.8</version>
+          <executions>
+            <execution>
+              <id>sign-artifacts</id>
+              <phase>verify</phase>
+              <goals>
+                <goal>sign</goal>
+              </goals>
+            </execution>
+          </executions>
+        </plugin>
+
+        <!-- Required for Maven Central publishing -->
+        <plugin>
+          <groupId>org.sonatype.central</groupId>
+          <artifactId>central-publishing-maven-plugin</artifactId>
+          <version>0.10.0</version>
+          <extensions>true</extensions>
+          <configuration>
+            <publishingServerId>central</publishingServerId>
+            <autoPublish>true</autoPublish>
+          </configuration>
+        </plugin>
+
+        <!-- Maven Clean Plugin -->
+        <plugin>
+          <groupId>org.apache.maven.plugins</groupId>
+          <artifactId>maven-clean-plugin</artifactId>
+          <version>3.5.0</version>
+          <configuration>
+            <filesets>
+              <fileset>
+                <directory>${project.build.directory}</directory>
+                <includes>
+                  <include>**/*</include>
+                </includes>
+                <followSymlinks>false</followSymlinks>
+              </fileset>
+            </filesets>
+          </configuration>
+        </plugin>
+
+        <!-- Skip deploying the parent POM to Maven Central -->
+        <plugin>
+          <groupId>org.apache.maven.plugins</groupId>
+          <artifactId>maven-deploy-plugin</artifactId>
+          <version>3.1.4</version>
+          <configuration>
+            <skip>true</skip>
+          </configuration>
+        </plugin>
+
+        <!-- Spring Boot Maven Plugin -->
+        <plugin>
+          <groupId>org.springframework.boot</groupId>
+          <artifactId>spring-boot-maven-plugin</artifactId>
+          <version>3.5.7</version>
+        </plugin>
+
+        <!-- Flatten to publish effective POMs without deploying the parent -->
+        <plugin>
+          <groupId>org.codehaus.mojo</groupId>
+          <artifactId>flatten-maven-plugin</artifactId>
+          <version>1.7.3</version>
+          <configuration>
+            <flattenMode>oss</flattenMode>
+            <updatePomFile>true</updatePomFile>
+          </configuration>
+          <executions>
+            <execution>
+              <id>flatten</id>
+              <phase>process-resources</phase>
+              <goals>
+                <goal>flatten</goal>
+              </goals>
+            </execution>
+            <execution>
+              <id>flatten-clean</id>
+              <phase>clean</phase>
+              <goals>
+                <goal>clean</goal>
+              </goals>
+            </execution>
+          </executions>
+        </plugin>
+      </plugins>
+    </pluginManagement>
+  </build>
+</project>
+

package/scalar-core/pom.xml

@@ -0,0 +1,92 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<project xmlns="http://maven.apache.org/POM/4.0.0"
+         xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
+         xsi:schemaLocation="http://maven.apache.org/POM/4.0.0
+         http://maven.apache.org/xsd/maven-4.0.0.xsd">
+  <modelVersion>4.0.0</modelVersion>
+
+  <parent>
+    <groupId>com.scalar.maven</groupId>
+    <artifactId>scalar-parent</artifactId>
+    <version>0.0.0</version>
+  </parent>
+
+  <artifactId>scalar-core</artifactId>
+  <packaging>jar</packaging>
+
+  <name>Scalar API Reference Core</name>
+  <description>Core framework-agnostic module for Scalar API Reference</description>
+
+  <dependencies>
+    <!-- Jackson for JSON serialization -->
+    <dependency>
+      <groupId>com.fasterxml.jackson.core</groupId>
+      <artifactId>jackson-databind</artifactId>
+    </dependency>
+
+    <!-- Test Dependencies -->
+    <dependency>
+      <groupId>org.junit.jupiter</groupId>
+      <artifactId>junit-jupiter</artifactId>
+      <scope>test</scope>
+    </dependency>
+
+    <dependency>
+      <groupId>org.mockito</groupId>
+      <artifactId>mockito-core</artifactId>
+      <scope>test</scope>
+    </dependency>
+
+    <dependency>
+      <groupId>org.mockito</groupId>
+      <artifactId>mockito-junit-jupiter</artifactId>
+      <scope>test</scope>
+    </dependency>
+
+    <dependency>
+      <groupId>org.assertj</groupId>
+      <artifactId>assertj-core</artifactId>
+      <scope>test</scope>
+    </dependency>
+  </dependencies>
+
+  <build>
+    <plugins>
+      <plugin>
+        <groupId>org.codehaus.mojo</groupId>
+        <artifactId>flatten-maven-plugin</artifactId>
+      </plugin>
+
+      <plugin>
+        <groupId>org.apache.maven.plugins</groupId>
+        <artifactId>maven-compiler-plugin</artifactId>
+      </plugin>
+
+      <plugin>
+        <groupId>org.apache.maven.plugins</groupId>
+        <artifactId>maven-surefire-plugin</artifactId>
+      </plugin>
+
+      <plugin>
+        <groupId>org.apache.maven.plugins</groupId>
+        <artifactId>maven-source-plugin</artifactId>
+      </plugin>
+
+      <plugin>
+        <groupId>org.apache.maven.plugins</groupId>
+        <artifactId>maven-javadoc-plugin</artifactId>
+      </plugin>
+
+      <plugin>
+        <groupId>org.apache.maven.plugins</groupId>
+        <artifactId>maven-gpg-plugin</artifactId>
+      </plugin>
+
+      <plugin>
+        <groupId>org.sonatype.central</groupId>
+        <artifactId>central-publishing-maven-plugin</artifactId>
+      </plugin>
+    </plugins>
+  </build>
+</project>
+

package/scalar-core/src/main/java/com/scalar/maven/core/ScalarConstants.java

@@ -0,0 +1,26 @@
+package com.scalar.maven.core;
+
+/**
+ * Constants used across the Scalar Java integration.
+ * <p>
+ * This class provides shared constants to avoid duplication across different
+ * modules and classes.
+ * </p>
+ */
+public final class ScalarConstants {
+
+    /**
+     * The default path where the Scalar API Reference interface is available.
+     */
+    public static final String DEFAULT_PATH = "/scalar";
+
+    /**
+     * The filename of the JavaScript bundle for the Scalar API Reference.
+     */
+    public static final String JS_FILENAME = "scalar.js";
+
+    private ScalarConstants() {
+        // Utility class - prevent instantiation
+    }
+}
+

package/scalar-core/src/main/java/com/scalar/maven/core/ScalarHtmlRenderer.java

@@ -0,0 +1,135 @@
+package com.scalar.maven.core;
+
+import com.fasterxml.jackson.core.JsonProcessingException;
+import com.fasterxml.jackson.databind.ObjectMapper;
+import com.scalar.maven.core.internal.ScalarConfiguration;
+import com.scalar.maven.core.internal.ScalarConfigurationMapper;
+
+import java.io.IOException;
+import java.io.InputStream;
+import java.nio.charset.StandardCharsets;
+import java.util.Objects;
+
+/**
+ * Static utility class for rendering HTML content for the Scalar API Reference interface.
+ *
+ * <p>
+ * This class is framework-agnostic and provides the core HTML rendering
+ * functionality. It loads the HTML template, serializes the configuration to JSON,
+ * and replaces placeholders with actual values.
+ * </p>
+ */
+public final class ScalarHtmlRenderer {
+
+    private static final String HTML_TEMPLATE_PATH = "/META-INF/resources/webjars/scalar/index.html";
+    private static final String JS_BUNDLE_PATH = "/META-INF/resources/webjars/scalar/" + ScalarConstants.JS_FILENAME;
+    private static final ObjectMapper OBJECT_MAPPER = new ObjectMapper();
+
+    private ScalarHtmlRenderer() {
+        // Utility class - prevent instantiation
+    }
+
+    /**
+     * Normalizes the base path by returning the default path if the provided
+     * base path is null or empty.
+     *
+     * @param basePath the base path to normalize
+     * @return the normalized base path, or {@link ScalarConstants#DEFAULT_PATH} if null or empty
+     */
+    private static String normalizeBasePath(String basePath) {
+        if (basePath == null || basePath.isEmpty()) {
+            return ScalarConstants.DEFAULT_PATH;
+        }
+        return basePath;
+    }
+
+    /**
+     * Renders the complete HTML content for the Scalar API Reference interface.
+     *
+     * @param properties the configuration properties for the Scalar integration
+     * @return the rendered HTML content
+     * @throws IOException if the HTML template cannot be loaded
+     */
+    public static String render(ScalarProperties properties) throws IOException {
+        Objects.requireNonNull(properties, "properties must not be null");
+
+        String basePath = normalizeBasePath(properties.getPath());
+
+        // Load the template HTML
+        InputStream templateStream = ScalarHtmlRenderer.class.getResourceAsStream(HTML_TEMPLATE_PATH);
+        if (templateStream == null) {
+            throw new IOException("HTML template not found at: " + HTML_TEMPLATE_PATH);
+        }
+
+        String html;
+        try (InputStream inputStream = templateStream) {
+            html = new String(inputStream.readAllBytes(), StandardCharsets.UTF_8);
+        }
+
+        // Build the JS bundle URL from the base path
+        String bundleUrl = buildJsBundleUrl(basePath);
+        String pageTitle = Objects.requireNonNullElse(properties.getPageTitle(), "Scalar API Reference");
+
+        // Serialize configuration to JSON
+        String configurationJson = buildConfigurationJson(properties);
+
+        // Replace placeholders
+        return html
+                .replace("__JS_BUNDLE_URL__", bundleUrl)
+                .replace("__PAGE_TITLE__", pageTitle)
+                .replace("__CONFIGURATION__", configurationJson);
+    }
+
+    /**
+     * Builds the URL for the Scalar JavaScript bundle based on the base path.
+     * Uses only the last path segment so the relative URL resolves correctly
+     * when the page is at basePath (avoids duplicate segments for multi-segment
+     * paths) and when deployed behind a reverse proxy with a context path.
+     *
+     * @param basePath the base path
+     * @return the relative path for the JavaScript bundle
+     */
+    private static String buildJsBundleUrl(String basePath) {
+        // Remove trailing slash to avoid double slashes when concatenating
+        String path = basePath;
+        if (path.endsWith("/")) {
+            path = path.substring(0, path.length() - 1);
+        }
+
+        int lastSlash = path.lastIndexOf('/');
+        String lastSegment = lastSlash >= 0 ? path.substring(lastSlash + 1) : path;
+        return lastSegment + "/" + ScalarConstants.JS_FILENAME;
+    }
+
+    /**
+     * Builds the configuration JSON for the Scalar API Reference.
+     *
+     * @param properties the properties to serialize
+     * @return the configuration JSON as a string
+     */
+    private static String buildConfigurationJson(ScalarProperties properties) {
+        try {
+            ScalarConfiguration config = ScalarConfigurationMapper.map(properties);
+            return OBJECT_MAPPER.writeValueAsString(config);
+        } catch (JsonProcessingException e) {
+            throw new RuntimeException("Failed to serialize Scalar configuration", e);
+        }
+    }
+
+    /**
+     * Gets the JavaScript bundle content.
+     *
+     * @return the JavaScript bundle content as bytes
+     * @throws IOException if the JavaScript file cannot be loaded
+     */
+    public static byte[] getScalarJsContent() throws IOException {
+        InputStream jsStream = ScalarHtmlRenderer.class.getResourceAsStream(JS_BUNDLE_PATH);
+        if (jsStream == null) {
+            throw new IOException("JavaScript bundle not found at: " + JS_BUNDLE_PATH);
+        }
+
+        try (InputStream inputStream = jsStream) {
+            return inputStream.readAllBytes();
+        }
+    }
+}