feat: Add Spec.fromPath(Path) with JSON+YAML auto-detect

Author: thced

README.md

@@ -85,12 +85,8 @@ A `null` body always produces a status-only response (`Content-Length: 0`, no bo
 ``` java
 public class YourServerLauncher {
   public static void main(String[] args) throws Exception {
-    Gson gson = new Gson();
-
-    // Parse spec to a generic Map (works for JSON; for YAML use SnakeYAML).
-    String text = Files.readString(Path.of("openapi.json"));
-    Map<String, Object> raw = (Map<String, Object>) gson.fromJson(text, Map.class);
-    Spec spec = Spec.from(raw);
+    // Gson is on the classpath, so we can load the spec in one line.
+    Spec spec = Spec.fromPath(Path.of("openapi.json"));
 
     // Handlers by operationId.
     Map<String, RequestHandler> handlers = new HashMap<>();
@@ -106,12 +102,7 @@ public class YourServerLauncher {
 }
 ```
 
-### YAML specifications
-For YAML, replace the JSON parsing line with SnakeYAML:
-``` java
-Map<String, Object> raw = new Yaml().load(Files.newInputStream(Path.of("openapi.yaml")));
-```
-The rest is identical.
+`Spec.fromPath(Path)` picks the parser by file extension: `.json` is parsed by Gson, `.yaml` / `.yml` by SnakeYAML. Both are optional dependencies of this library — the same Gson that powers the built-in JSON `TypeMapper`, and the same SnakeYAML you'd add explicitly to parse YAML. If the required parser isn't on the classpath the call fails with `IllegalStateException`; parse the file yourself and use `Spec.from(Map<String, Object>)` instead. Any other extension is rejected.
 
 ### JSON mapping
 

src/main/java/com/retailsvc/http/spec/Spec.java

@@ -2,7 +2,12 @@
 
 import com.retailsvc.http.spec.schema.Schema;
 import com.retailsvc.http.spec.schema.SchemaParser;
+import java.io.IOException;
+import java.io.UncheckedIOException;
+import java.lang.reflect.Method;
 import java.net.URI;
+import java.nio.file.Files;
+import java.nio.file.Path;
 import java.util.ArrayList;
 import java.util.LinkedHashMap;
 import java.util.List;
@@ -36,6 +41,91 @@ static Map<String, Object> extractExtensions(Map<String, Object> raw) {
     return Map.copyOf(out);
   }
 
+  private static final String GSON_CLASS = "com.google.gson.Gson";
+  private static final String SNAKEYAML_CLASS = "org.yaml.snakeyaml.Yaml";
+
+  /**
+   * Reads an OpenAPI specification from {@code path}. Picks the parser by file extension:
+   *
+   * <ul>
+   *   <li>{@code .json} → Gson must be on the classpath.
+   *   <li>{@code .yaml} or {@code .yml} → SnakeYAML must be on the classpath.
+   * </ul>
+   *
+   * <p>Both Gson and SnakeYAML are optional dependencies of this library. If the parser for the
+   * file's extension is not present, throws {@link IllegalStateException} — register your own
+   * parser and call {@link #from(Map)} instead.
+   *
+   * @throws UncheckedIOException if the file cannot be read
+   * @throws IllegalStateException if the required parser is not on the classpath, or if the file
+   *     has an unrecognised extension
+   */
+  public static Spec fromPath(Path path) {
+    String text;
+    try {
+      text = Files.readString(path);
+    } catch (IOException e) {
+      throw new UncheckedIOException("Failed to read OpenAPI spec from " + path, e);
+    }
+    String name = path.getFileName().toString().toLowerCase(Locale.ROOT);
+    Map<String, Object> raw;
+    if (name.endsWith(".json")) {
+      raw = parseJson(text);
+    } else if (name.endsWith(".yaml") || name.endsWith(".yml")) {
+      raw = parseYaml(text);
+    } else {
+      throw new IllegalStateException(
+          "Unrecognised OpenAPI spec extension for "
+              + path
+              + " — expected .json, .yaml, or .yml. Parse the file yourself and call"
+              + " Spec.from(Map<String, Object>) instead.");
+    }
+    return from(raw);
+  }
+
+  private static Map<String, Object> parseJson(String text) {
+    Class<?> gsonClass = loadOptional(GSON_CLASS, "JSON", "Gson");
+    try {
+      Object gson = gsonClass.getDeclaredConstructor().newInstance();
+      Method fromJson = gsonClass.getMethod("fromJson", String.class, Class.class);
+      @SuppressWarnings("unchecked")
+      Map<String, Object> raw = (Map<String, Object>) fromJson.invoke(gson, text, Map.class);
+      return raw;
+    } catch (ReflectiveOperationException e) {
+      throw new IllegalStateException("Failed to parse OpenAPI spec via Gson", e);
+    }
+  }
+
+  private static Map<String, Object> parseYaml(String text) {
+    Class<?> yamlClass = loadOptional(SNAKEYAML_CLASS, "YAML", "SnakeYAML");
+    try {
+      Object yaml = yamlClass.getDeclaredConstructor().newInstance();
+      Method load = yamlClass.getMethod("load", String.class);
+      @SuppressWarnings("unchecked")
+      Map<String, Object> raw = (Map<String, Object>) load.invoke(yaml, text);
+      return raw;
+    } catch (ReflectiveOperationException e) {
+      throw new IllegalStateException("Failed to parse OpenAPI spec via SnakeYAML", e);
+    }
+  }
+
+  private static Class<?> loadOptional(String className, String format, String libName) {
+    try {
+      return Class.forName(className, false, Spec.class.getClassLoader());
+    } catch (ClassNotFoundException e) {
+      throw new IllegalStateException(
+          "Spec.fromPath requires "
+              + libName
+              + " on the classpath for "
+              + format
+              + " specs. Add a "
+              + libName
+              + " dependency, or parse the file yourself and call"
+              + " Spec.from(Map<String, Object>) instead.",
+          e);
+    }
+  }
+
   @SuppressWarnings("unchecked")
   public static Spec from(Map<String, Object> raw) {
     String openapi = (String) raw.get("openapi");

src/test/java/com/retailsvc/http/spec/SpecFromPathTest.java

@@ -0,0 +1,40 @@
+package com.retailsvc.http.spec;
+
+import static org.assertj.core.api.Assertions.assertThat;
+
+import java.nio.file.Path;
+import org.junit.jupiter.api.Test;
+
+class SpecFromPathTest {
+
+  @Test
+  void loadsJsonSpecViaGson() throws Exception {
+    Path resource = Path.of(getClass().getResource("/openapi.json").toURI());
+
+    Spec spec = Spec.fromPath(resource);
+
+    assertThat(spec.openapi()).startsWith("3.1");
+    assertThat(spec.basePath()).isEqualTo("/api/v1");
+    assertThat(spec.operations()).isNotEmpty();
+  }
+
+  @Test
+  void loadsYamlSpecViaSnakeYaml() throws Exception {
+    Path resource = Path.of(getClass().getResource("/openapi.yaml").toURI());
+
+    Spec spec = Spec.fromPath(resource);
+
+    assertThat(spec.openapi()).startsWith("3.1");
+    assertThat(spec.operations()).isNotEmpty();
+  }
+
+  @Test
+  void rejectsUnknownExtension(@org.junit.jupiter.api.io.TempDir Path tmp) throws Exception {
+    Path unknown = tmp.resolve("spec.txt");
+    java.nio.file.Files.writeString(unknown, "{}");
+
+    org.assertj.core.api.Assertions.assertThatThrownBy(() -> Spec.fromPath(unknown))
+        .isInstanceOf(IllegalStateException.class)
+        .hasMessageContaining("Unrecognised OpenAPI spec extension");
+  }
+}