Support loading specifications from a remote URL (Apicurio / HTTP)

`specFile.filePath` may now be an http/https/ftp/file URL; the spec is fetched
from that URL at generation time instead of the filesystem/classpath. This
enables consuming specs published in an Apicurio Registry (artifacts served over
HTTP) and any URL-addressable source, for both the OpenAPI and AsyncAPI
generators.

- PathUtil.isRemoteUri detects URL-scheme paths.
- SchemaUtil.readFile fetches remote specs directly (shared main-spec reader for
  both generators).
- New RemoteFileLocation resolves external $refs relative to a remote spec's URL.
- AsyncApiGenerator / BaseAsyncApiHandler resolve remote spec locations.
- ApiTool.nodeFromFile handles URL references.
- OpenApiGenerator uses the URL parent as the $ref base when the spec is remote.

Adds PathUtilTest and a SchemaUtil URL-loading test (file:// URL, network-free).
Documents the Apicurio/URL usage in the README.

Bumps version 6.5.1 -> 6.6.0 (new feature).

Closes joseegman-idoneea#7

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

Author: joseegarcia

README.md

@@ -834,3 +834,31 @@ from a local JAR containing `contracts/event-api.yml` in its resources:
   </dependencies>
 </plugin>
 ```
+
+## Loading specifications from a remote URL (Apicurio Registry, HTTP)
+
+`filePath` also accepts a remote URL (`http`, `https`, `ftp` or `file` scheme). When it does,
+the specification is downloaded at generation time instead of being read from the filesystem or
+the classpath. This works for both OpenAPI and AsyncAPI specs.
+
+This is the mechanism to consume a spec published in an **Apicurio Registry**, whose artifacts are
+served over HTTP. Point `filePath` at the artifact's content endpoint, for example:
+
+```xml
+<specFile>
+    <filePath>https://my-apicurio-host/apis/registry/v2/groups/default/artifacts/my-api</filePath>
+    <apiPackage>com.sngular.apigenerator.openapi.api</apiPackage>
+    <modelPackage>com.sngular.apigenerator.openapi.model</modelPackage>
+</specFile>
+```
+
+Gradle:
+
+```groovy
+filePath = 'https://my-apicurio-host/apis/registry/v2/groups/default/artifacts/my-api'
+```
+
+Notes:
+- Only publicly reachable URLs are supported for now; authenticated registries (tokens/headers)
+  are not yet handled.
+- External `$ref`s are resolved relative to the spec's URL when the spec itself is remote.

multiapi-engine/pom.xml

@@ -4,7 +4,7 @@
 
   <groupId>com.sngular</groupId>
   <artifactId>multiapi-engine</artifactId>
-  <version>6.5.1</version>
+  <version>6.6.0</version>
   <packaging>jar</packaging>
 
   <properties>

multiapi-engine/src/main/java/com/sngular/api/generator/plugin/asyncapi/AsyncApiGenerator.java

@@ -26,6 +26,7 @@
 import com.sngular.api.generator.plugin.common.files.ClasspathFileLocation;
 import com.sngular.api.generator.plugin.common.files.DirectoryFileLocation;
 import com.sngular.api.generator.plugin.common.files.FileLocation;
+import com.sngular.api.generator.plugin.common.files.RemoteFileLocation;
 import com.sngular.api.generator.plugin.common.tools.PathUtil;
 import lombok.extern.slf4j.Slf4j;
 import org.apache.commons.lang3.tuple.ImmutablePair;
@@ -85,6 +86,15 @@ public final void processFileSpec(final List<SpecFile> specsListFile) {
 
   private static Pair<InputStream, FileLocation> resolveYmlLocation(final String ymlFilePath) throws FileNotFoundException {
     log.debug("Resolving YAML file location:{}", ymlFilePath);
+    if (PathUtil.isRemoteUri(ymlFilePath)) {
+      log.debug("Loading spec from remote URL");
+      try {
+        final URI uri = URI.create(ymlFilePath);
+        return new ImmutablePair<>(uri.toURL().openStream(), new RemoteFileLocation(uri.resolve(".")));
+      } catch (final IOException e) {
+        throw new FileNotFoundException("Could not open remote YAML file: " + ymlFilePath);
+      }
+    }
     final InputStream classPathInput = AsyncApiGenerator.class.getClassLoader().getResourceAsStream(ymlFilePath);
     final InputStream ymlFile;
     final FileLocation ymlParentPath;

multiapi-engine/src/main/java/com/sngular/api/generator/plugin/asyncapi/handler/BaseAsyncApiHandler.java

@@ -21,6 +21,8 @@
 import com.sngular.api.generator.plugin.asyncapi.parameter.SpecFile;
 import com.sngular.api.generator.plugin.asyncapi.template.TemplateFactory;
 import com.sngular.api.generator.plugin.common.files.ClasspathFileLocation;
+import com.sngular.api.generator.plugin.common.files.RemoteFileLocation;
+import com.sngular.api.generator.plugin.common.tools.PathUtil;
 import com.sngular.api.generator.plugin.common.files.DirectoryFileLocation;
 import com.sngular.api.generator.plugin.common.files.FileLocation;
 import com.sngular.api.generator.plugin.common.model.CommonSpecFile;
@@ -108,6 +110,9 @@ protected BaseAsyncApiHandler(
   }
 
   protected static FileLocation resolveYmlLocation(final String ymlFilePath) throws IOException, URISyntaxException {
+    if (PathUtil.isRemoteUri(ymlFilePath)) {
+      return new RemoteFileLocation(URI.create(ymlFilePath).resolve("."));
+    }
     final var classPathInput = BaseAsyncApiHandler.class.getClassLoader().getResource(ymlFilePath);
     if (Objects.nonNull(classPathInput)) {
       return new ClasspathFileLocation(getParentUri(classPathInput.toURI()));

multiapi-engine/src/main/java/com/sngular/api/generator/plugin/common/files/RemoteFileLocation.java

@@ -0,0 +1,37 @@
+/*
+ *  This Source Code Form is subject to the terms of the Mozilla Public
+ *  * License, v. 2.0. If a copy of the MPL was not distributed with this
+ *  * file, You can obtain one at https://mozilla.org/MPL/2.0/.
+ */
+
+package com.sngular.api.generator.plugin.common.files;
+
+import java.io.IOException;
+import java.io.InputStream;
+import java.net.URI;
+import java.net.URL;
+
+/**
+ * {@link FileLocation} for specifications loaded from a remote URL (e.g. an Apicurio Registry
+ * artifact served over HTTP). Relative sibling files (external {@code $ref}s) are resolved
+ * against the spec's base URI and fetched over the same protocol.
+ */
+public class RemoteFileLocation implements FileLocation {
+
+  private final URI baseUri;
+
+  public RemoteFileLocation(final URI baseUri) {
+    this.baseUri = baseUri;
+  }
+
+  @Override
+  public InputStream getFileAtLocation(final String filename) throws IOException {
+    final URL target = baseUri.resolve(filename).toURL();
+    return target.openStream();
+  }
+
+  @Override
+  public URI path() {
+    return baseUri;
+  }
+}

multiapi-engine/src/main/java/com/sngular/api/generator/plugin/common/tools/ApiTool.java

@@ -453,8 +453,10 @@ public static boolean hasComponents(final JsonNode node) {
 
   public static JsonNode nodeFromFile(final FileLocation ymlParent, final String filePath, final FactoryTypeEnum factoryTypeEnum) throws IOException {
     final InputStream file;
-    // Check if path is absolute first
-    if (PathUtil.isAbsolutePath(filePath)) {
+    // Remote references (http/https/ftp/file URLs) are fetched directly from their URL.
+    if (PathUtil.isRemoteUri(filePath)) {
+      file = new java.net.URL(filePath).openStream();
+    } else if (PathUtil.isAbsolutePath(filePath)) {
       // For absolute paths, open directly
       file = new FileInputStream(filePath);
     } else if (filePath.startsWith(PACKAGE_SEPARATOR_STR) || filePath.matches("^\\w.*$")) {

multiapi-engine/src/main/java/com/sngular/api/generator/plugin/common/tools/PathUtil.java

@@ -37,4 +37,17 @@ public static boolean isAbsolutePath(final String filePath) {
       return false;
     }
   }
+
+  /**
+   * Checks whether a spec path points to a remote/URL location that must be fetched via a
+   * {@link java.net.URL} stream rather than the filesystem or classpath. Enables loading
+   * specifications from HTTP(S) endpoints such as an Apicurio Registry artifact.
+   *
+   * @param filePath the spec path to check
+   * @return true if the path uses an http, https, ftp or file scheme
+   */
+  public static boolean isRemoteUri(final String filePath) {
+    return StringUtils.isNotEmpty(filePath)
+           && filePath.matches("^(?i)(https?|ftp|file)://.*");
+  }
 }

multiapi-engine/src/main/java/com/sngular/api/generator/plugin/common/tools/SchemaUtil.java

@@ -137,6 +137,12 @@ private static String readFile(final URI rootFilePath, final String filePath) th
       throw new IllegalArgumentException("File Path cannot be empty");
     }
 
+    // Remote specifications (http/https/ftp/file URLs, e.g. an Apicurio Registry artifact) are
+    // fetched directly from their URL, bypassing classpath and filesystem resolution.
+    if (PathUtil.isRemoteUri(filePath)) {
+      return readFromUrl(new URL(filePath));
+    }
+
     // Normalize the incoming filePath: remove leading './' and replace backslashes with forward slashes
     final String cleaned = cleanUpPath(filePath).replace('\\', '/');
 
@@ -161,6 +167,10 @@ private static String readFile(final URI rootFilePath, final String filePath) th
         }
       }
     }
+    return readFromUrl(fileURL);
+  }
+
+  private static String readFromUrl(final URL fileURL) {
     final var sb = new StringBuilder();
     try (BufferedReader reader = new BufferedReader(new InputStreamReader(fileURL.openStream()))) {
       String inputLine;

multiapi-engine/src/main/java/com/sngular/api/generator/plugin/openapi/OpenApiGenerator.java

@@ -8,6 +8,7 @@
 
 import java.io.File;
 import java.io.IOException;
+import java.net.URI;
 import java.nio.file.Path;
 import java.util.ArrayList;
 import java.util.HashSet;
@@ -23,6 +24,7 @@
 import com.sngular.api.generator.plugin.common.tools.ApiTool;
 import com.sngular.api.generator.plugin.common.tools.MapperContentUtil;
 import com.sngular.api.generator.plugin.common.tools.MapperUtil;
+import com.sngular.api.generator.plugin.common.tools.PathUtil;
 import com.sngular.api.generator.plugin.exception.GeneratorTemplateException;
 import com.sngular.api.generator.plugin.openapi.exception.DuplicateModelClassException;
 import com.sngular.api.generator.plugin.openapi.model.AuthObject;
@@ -99,7 +101,10 @@ private void processFile(final SpecFile specFile) {
 
     final JsonNode openAPI = OpenApiUtil.getPojoFromSpecFile(baseDir, specFile);
     OpenApiUtil.mergeWebhooksIntoPaths(openAPI);
-    OpenApiUtil.solvePathRefs(openAPI, baseDir.resolve(specFile.getFilePath()).getParent().toUri());
+    final URI specBaseUri = PathUtil.isRemoteUri(specFile.getFilePath())
+                                ? URI.create(specFile.getFilePath()).resolve(".")
+                                : baseDir.resolve(specFile.getFilePath()).getParent().toUri();
+    OpenApiUtil.solvePathRefs(openAPI, specBaseUri);
     final String clientPackage = specFile.getClientPackage();
 
     if (specFile.isCallMode()) {

multiapi-engine/src/test/java/com/sngular/api/generator/plugin/common/tools/PathUtilTest.java

@@ -0,0 +1,34 @@
+/*
+ *  This Source Code Form is subject to the terms of the Mozilla Public
+ *  * License, v. 2.0. If a copy of the MPL was not distributed with this
+ *  * file, You can obtain one at https://mozilla.org/MPL/2.0/.
+ */
+
+package com.sngular.api.generator.plugin.common.tools;
+
+import static org.junit.jupiter.api.Assertions.assertFalse;
+import static org.junit.jupiter.api.Assertions.assertTrue;
+
+import org.junit.jupiter.api.Test;
+
+class PathUtilTest {
+
+  @Test
+  void isRemoteUriDetectsUrlSchemes() {
+    assertTrue(PathUtil.isRemoteUri("http://registry/apis/registry/v2/groups/g/artifacts/a"));
+    assertTrue(PathUtil.isRemoteUri("https://example.com/openapi.yml"));
+    assertTrue(PathUtil.isRemoteUri("HTTPS://EXAMPLE.COM/openapi.yml"));
+    assertTrue(PathUtil.isRemoteUri("ftp://host/spec.yml"));
+    assertTrue(PathUtil.isRemoteUri("file:///tmp/spec.yml"));
+  }
+
+  @Test
+  void isRemoteUriRejectsLocalPaths() {
+    assertFalse(PathUtil.isRemoteUri("./src/main/resources/api/api.yml"));
+    assertFalse(PathUtil.isRemoteUri("/absolute/path/api.yml"));
+    assertFalse(PathUtil.isRemoteUri("contracts/event-api.yml"));
+    assertFalse(PathUtil.isRemoteUri("C:\\api\\api.yml"));
+    assertFalse(PathUtil.isRemoteUri(""));
+    assertFalse(PathUtil.isRemoteUri(null));
+  }
+}