Merge pull request #37 from quarkiverse/kogito-6752

Add support to generate stubs from any InputStream

Author: fjtirado

README.md

@@ -100,12 +100,17 @@ See the [integration-tests](integration-tests) module for more information of ho
 
 ## Authentication Support
 
-If your OpenAPI specification file has `securitySchemes` [definitions](https://spec.openapis.org/oas/v3.1.0#security-scheme-object), the inner generator will [register `ClientRequestFilter`s providers](https://download.eclipse.org/microprofile/microprofile-rest-client-2.0/microprofile-rest-client-spec-2.0.html#_provider_declaration) for you to implement the given authentication mechanism.
+If your OpenAPI specification file has `securitySchemes` [definitions](https://spec.openapis.org/oas/v3.1.0#security-scheme-object), the inner generator
+will [register `ClientRequestFilter`s providers](https://download.eclipse.org/microprofile/microprofile-rest-client-2.0/microprofile-rest-client-spec-2.0.html#_provider_declaration) for you to
+implement the given authentication mechanism.
 
-To provide the credentials for your application, you can use the [Quarkus configuration support](https://quarkus.io/guides/config). The configuration key is composed using this pattern: `[base_package].security.auth.[security_scheme_name]/[auth_property_name]`. Where:
+To provide the credentials for your application, you can use the [Quarkus configuration support](https://quarkus.io/guides/config). The configuration key is composed using this
+pattern: `[base_package].security.auth.[security_scheme_name]/[auth_property_name]`. Where:
 
 - `base_package` is the package name you gave when configuring the code generation using `quarkus.openapi-generator.codegen.spec.[open_api_file].base-package` property.
-- `security_scheme_name` is the name of the [security scheme object definition](https://spec.openapis.org/oas/v3.1.0#security-scheme-object) in the OpenAPI file. Given the following excerpt, we have `api_key` and `basic_auth` security schemes:
+- `security_scheme_name` is the name of the [security scheme object definition](https://spec.openapis.org/oas/v3.1.0#security-scheme-object) in the OpenAPI file. Given the following excerpt, we
+  have `api_key` and `basic_auth` security schemes:
+
 ```json
 {
   "securitySchemes": {
@@ -121,6 +126,7 @@ To provide the credentials for your application, you can use the [Quarkus config
   }
 }
 ```
+
 - `auth_property_name` varies depending on the authentication provider. For example, for Basic Authentication we have `username` and `password`. See the following sections for more details.
 
 > Tip: on production environments you will likely to use [HashiCorp Vault](https://quarkiverse.github.io/quarkiverse-docs/quarkus-vault/dev/index.html) or [Kubernetes Secrets](https://kubernetes.io/docs/concepts/configuration/secret/) to provide this information for your application.
@@ -150,14 +156,15 @@ Similarly to bearer token, the API Key Authentication also has the token entry k
 | -------------| --------------------------------------------------------------| --------------------------------------------------- |
 | API Key      | `[base_package].security.auth.[security_scheme_name]/api-key` | `org.acme.openapi.security.auth.apikey/api-key` |
 
-The API Key scheme has an additional property that requires where to add the API key in the request token: header, cookie or query. The inner provider takes care of that for you. 
+The API Key scheme has an additional property that requires where to add the API key in the request token: header, cookie or query. The inner provider takes care of that for you.
 
 ## Circuit Breaker
 
 You can define the [CircuitBreaker annotation from MicroProfile Fault Tolerance](https://microprofile.io/project/eclipse/microprofile-fault-tolerance/spec/src/main/asciidoc/circuitbreaker.asciidoc)
 in your generated classes by setting the desired configuration in `application.properties`.
 
 Let's say you have the following OpenAPI definition:
+
 ````json
 {
   "openapi": "3.0.3",
@@ -207,17 +214,17 @@ And you want to configure Circuit Breaker for the `/bye` endpoint, you can do it
 Add the [SmallRye Fault Tolerance extension](https://quarkus.io/guides/smallrye-fault-tolerance) to your project's `pom.xml` file:
 
 ````xml
+
 <dependency>
-    <groupId>io.quarkus</groupId>
-    <artifactId>quarkus-smallrye-fault-tolerance</artifactId>
+  <groupId>io.quarkus</groupId>
+  <artifactId>quarkus-smallrye-fault-tolerance</artifactId>
 </dependency>
 ````
 
 Assuming your Open API spec file is in `src/main/openapi/simple-openapi.json`, add the following configuration to your `application.properties` file:
 
 ````properties
 quarkus.openapi-generator.codegen.spec."simple-openapi.json".base-package=org.acme.openapi.simple
-
 # Enables the CircuitBreaker extension for the byeGet method from the DefaultApi class
 org.acme.openapi.simple.api.DefaultApi/byeGet/CircuitBreaker/enabled=true
 ````
@@ -233,6 +240,7 @@ import java.io.InputStream;
 import java.io.OutputStream;
 import java.util.List;
 import java.util.Map;
+
 import javax.ws.rs.*;
 import javax.ws.rs.core.Response;
 import javax.ws.rs.core.MediaType;
@@ -243,30 +251,38 @@ public interface DefaultApi {
 
     @GET
     @Path("/bye")
-    @Produces({"text/plain"})
+    @Produces({ "text/plain" })
     @org.eclipse.microprofile.faulttolerance.CircuitBreaker
     public String byeGet();
 
     @GET
     @Path("/hello")
-    @Produces({"text/plain"})
+    @Produces({ "text/plain" })
     public String helloGet();
 
 }
 ````
 
-You can also override the default Circuit Breaker configuration by setting the properties in `application.properties` [just as you would for a traditional MicroProfile application](https://quarkus.io/guides/smallrye-fault-tolerance#runtime-configuration):
+You can also override the default Circuit Breaker configuration by setting the properties
+in `application.properties` [just as you would for a traditional MicroProfile application](https://quarkus.io/guides/smallrye-fault-tolerance#runtime-configuration):
 
 ````properties
-org.acme.openapi.simple.api.DefaultApi/byeGet/CircuitBreaker/failOn = java.lang.IllegalArgumentException,java.lang.NullPointerException
-org.acme.openapi.simple.api.DefaultApi/byeGet/CircuitBreaker/skipOn = java.lang.NumberFormatException
-org.acme.openapi.simple.api.DefaultApi/byeGet/CircuitBreaker/delay = 33
-org.acme.openapi.simple.api.DefaultApi/byeGet/CircuitBreaker/delayUnit = MILLIS
-org.acme.openapi.simple.api.DefaultApi/byeGet/CircuitBreaker/requestVolumeThreshold = 42
-org.acme.openapi.simple.api.DefaultApi/byeGet/CircuitBreaker/failureRatio = 3.14
-org.acme.openapi.simple.api.DefaultApi/byeGet/CircuitBreaker/successThreshold = 22
+org.acme.openapi.simple.api.DefaultApi/byeGet/CircuitBreaker/failOn=java.lang.IllegalArgumentException,java.lang.NullPointerException
+org.acme.openapi.simple.api.DefaultApi/byeGet/CircuitBreaker/skipOn=java.lang.NumberFormatException
+org.acme.openapi.simple.api.DefaultApi/byeGet/CircuitBreaker/delay=33
+org.acme.openapi.simple.api.DefaultApi/byeGet/CircuitBreaker/delayUnit=MILLIS
+org.acme.openapi.simple.api.DefaultApi/byeGet/CircuitBreaker/requestVolumeThreshold=42
+org.acme.openapi.simple.api.DefaultApi/byeGet/CircuitBreaker/failureRatio=3.14
+org.acme.openapi.simple.api.DefaultApi/byeGet/CircuitBreaker/successThreshold=22
 ````
 
+## Generating files via InputStream
+
+Having the files in the `src/main/openapi` directory will generate the REST stubs by default. Alternatively, you can implement the `io.quarkiverse.openapi.generator.codegen.OpenApiSpecInputProvider`
+interface to provide a list of `InputStream`s of OpenAPI specification files. This is useful in scenarios where you want to dynamically generate the client code without having the target spec file
+saved locally in your project.
+
+See the example implementation [here](test-utils/src/main/java/io/quarkiverse/openapi/generator/testutils/codegen/ClassPathPetstoreOpenApiSpecInputProvider.java)
 
 ## Known Limitations
 

deployment/pom.xml

@@ -100,7 +100,6 @@
     <dependency>
       <groupId>io.quarkiverse.openapi.generator</groupId>
       <artifactId>quarkus-openapi-generator-test-utils</artifactId>
-      <version>${project.version}</version>
       <scope>test</scope>
     </dependency>
 

deployment/src/main/java/io/quarkiverse/openapi/generator/deployment/codegen/OpenApiGeneratorCodeGenBase.java

@@ -42,15 +42,7 @@ public boolean trigger(CodeGenContext context) throws CodeGenException {
                         .map(Path::toString)
                         .filter(s -> s.endsWith(this.inputExtension()))
                         .map(Path::of).forEach(openApiFilePath -> {
-                            final OpenApiClientGeneratorWrapper generator = new OpenApiClientGeneratorWrapper(
-                                    openApiFilePath.normalize(), outDir)
-                                            .withCircuitBreakerConfiguration(CircuitBreakerConfigurationParser.parse(
-                                                    context.config()));
-
-                            context.config()
-                                    .getOptionalValue(getResolvedBasePackageProperty(openApiFilePath), String.class)
-                                    .ifPresent(generator::withBasePackage);
-                            generator.generate();
+                            this.generate(context, openApiFilePath, outDir);
                         });
             } catch (IOException e) {
                 throw new CodeGenException("Failed to generate java files from OpenApi files in " + openApiDir.toAbsolutePath(),
@@ -60,4 +52,16 @@ public boolean trigger(CodeGenContext context) throws CodeGenException {
         }
         return false;
     }
+
+    protected void generate(CodeGenContext context, final Path openApiFilePath, final Path outDir) {
+        // TODO: do not generate with the output dir has generated files and the openapi file has the same checksum of the previous runz
+        final OpenApiClientGeneratorWrapper generator = new OpenApiClientGeneratorWrapper(
+                openApiFilePath.normalize(), outDir)
+                        .withCircuitBreakerConfiguration(CircuitBreakerConfigurationParser.parse(
+                                context.config()));
+        context.config()
+                .getOptionalValue(getResolvedBasePackageProperty(openApiFilePath), String.class)
+                .ifPresent(generator::withBasePackage);
+        generator.generate();
+    }
 }

deployment/src/main/java/io/quarkiverse/openapi/generator/deployment/codegen/OpenApiGeneratorStreamCodeGen.java

@@ -0,0 +1,89 @@
+package io.quarkiverse.openapi.generator.deployment.codegen;
+
+import java.io.FileOutputStream;
+import java.io.IOException;
+import java.io.UncheckedIOException;
+import java.nio.channels.Channels;
+import java.nio.channels.ReadableByteChannel;
+import java.nio.file.Path;
+import java.nio.file.Paths;
+import java.util.List;
+import java.util.ServiceLoader;
+import java.util.stream.Collectors;
+
+import org.eclipse.microprofile.config.Config;
+import org.slf4j.Logger;
+import org.slf4j.LoggerFactory;
+
+import io.quarkiverse.openapi.generator.codegen.OpenApiSpecInputProvider;
+import io.quarkiverse.openapi.generator.codegen.SpecInputModel;
+import io.quarkus.bootstrap.prebuild.CodeGenException;
+import io.quarkus.deployment.CodeGenContext;
+
+public class OpenApiGeneratorStreamCodeGen extends OpenApiGeneratorCodeGenBase {
+
+    private static final Logger LOGGER = LoggerFactory.getLogger(OpenApiGeneratorStreamCodeGen.class);
+
+    private List<OpenApiSpecInputProvider> providers;
+    private final ServiceLoader<OpenApiSpecInputProvider> loader;
+
+    public OpenApiGeneratorStreamCodeGen() {
+        loader = ServiceLoader.load(OpenApiSpecInputProvider.class);
+    }
+
+    private void loadServices() {
+        loader.reload();
+        providers = loader.stream().map(ServiceLoader.Provider::get).collect(Collectors.toList());
+        LOGGER.debug("Loaded {} OpenApiSpecInputProviders", providers);
+    }
+
+    @Override
+    public String providerId() {
+        return "open-api-stream";
+    }
+
+    // unused by this CodeGenProvider since we rely on the input coming from ServiceLoaders
+    @Override
+    public String inputExtension() {
+        return ".yaml";
+    }
+
+    // unused by this CodeGenProvider since we rely on the input coming from ServiceLoaders
+    @Override
+    public String inputDirectory() {
+        return "openapi";
+    }
+
+    @Override
+    public boolean trigger(CodeGenContext context) throws CodeGenException {
+        final Path outDir = context.outDir();
+        boolean generated = false;
+
+        for (final OpenApiSpecInputProvider provider : this.providers) {
+            for (SpecInputModel inputModel : provider.read()) {
+                LOGGER.debug("Processing OpenAPI spec input model {}", inputModel);
+                if (inputModel == null) {
+                    throw new CodeGenException("SpecInputModel from provider " + provider + " is null");
+                }
+                final Path openApiFilePath = Paths.get(outDir.toString(), inputModel.getFileName());
+                try (ReadableByteChannel channel = Channels.newChannel(inputModel.getInputStream());
+                        FileOutputStream output = new FileOutputStream(openApiFilePath.toString())) {
+                    output.getChannel().transferFrom(channel, 0, Integer.MAX_VALUE);
+                    LOGGER.debug("Saved OpenAPI spec input model in {}", openApiFilePath);
+                    this.generate(context, openApiFilePath, outDir);
+                    generated = true;
+                } catch (IOException e) {
+                    throw new UncheckedIOException("Failed to save InputStream from provider " + provider + " into location ",
+                            e);
+                }
+            }
+        }
+        return generated;
+    }
+
+    @Override
+    public boolean shouldRun(Path sourceDir, Config config) {
+        this.loadServices();
+        return !this.providers.isEmpty();
+    }
+}

deployment/src/main/resources/META-INF/services/io.quarkus.deployment.CodeGenProvider

@@ -1,3 +1,4 @@
 io.quarkiverse.openapi.generator.deployment.codegen.OpenApiGeneratorJsonCodeGen
 io.quarkiverse.openapi.generator.deployment.codegen.OpenApiGeneratorYamlCodeGen
 io.quarkiverse.openapi.generator.deployment.codegen.OpenApiGeneratorYmlCodeGen
+io.quarkiverse.openapi.generator.deployment.codegen.OpenApiGeneratorStreamCodeGen

integration-tests/pom.xml

@@ -36,11 +36,11 @@
       <artifactId>microprofile-fault-tolerance-api</artifactId>
     </dependency>
 
+    <!-- exceptionally here, we are using the test utils with default scope because of the ClassPathOpenApiSpecInputProvider -->
     <dependency>
       <groupId>io.quarkiverse.openapi.generator</groupId>
       <artifactId>quarkus-openapi-generator-test-utils</artifactId>
-      <version>${project.version}</version>
-      <scope>test</scope>
+      <scope>compile</scope>
     </dependency>
     <dependency>
       <groupId>io.quarkus</groupId>

integration-tests/src/main/resources/META-INF/services/io.quarkiverse.openapi.generator.codegen.OpenApiSpecInputProvider

@@ -0,0 +1 @@
+io.quarkiverse.openapi.generator.testutils.codegen.ClassPathPetstoreOpenApiSpecInputProvider

pom.xml

@@ -41,6 +41,11 @@
         <artifactId>microprofile-fault-tolerance-api</artifactId>
         <version>${version.org.eclipse.microprofile.fault-tolerance}</version>
       </dependency>
+      <dependency>
+        <groupId>io.quarkiverse.openapi.generator</groupId>
+        <artifactId>quarkus-openapi-generator</artifactId>
+        <version>${project.version}</version>
+      </dependency>
       <!-- Test -->
       <dependency>
         <groupId>com.github.javaparser</groupId>
@@ -54,6 +59,12 @@
         <version>${version.org.assertj}</version>
         <scope>test</scope>
       </dependency>
+      <dependency>
+        <groupId>io.quarkiverse.openapi.generator</groupId>
+        <artifactId>quarkus-openapi-generator-test-utils</artifactId>
+        <version>${project.version}</version>
+        <scope>test</scope>
+      </dependency>
     </dependencies>
   </dependencyManagement>
   <build>

runtime/src/main/java/io/quarkiverse/openapi/generator/codegen/OpenApiSpecInputProvider.java

@@ -0,0 +1,18 @@
+package io.quarkiverse.openapi.generator.codegen;
+
+import java.io.InputStream;
+import java.util.List;
+
+/**
+ * Provider interface for clients to dynamically provide their own OpenAPI specification files.
+ */
+public interface OpenApiSpecInputProvider {
+
+    /**
+     * Fetch OpenAPI specification files from a given source.
+     *
+     * @return a list of spec files in {@link InputStream} format.
+     */
+    List<SpecInputModel> read();
+
+}

runtime/src/main/java/io/quarkiverse/openapi/generator/codegen/SpecInputModel.java

@@ -0,0 +1,51 @@
+package io.quarkiverse.openapi.generator.codegen;
+
+import static java.util.Objects.requireNonNull;
+
+import java.io.InputStream;
+import java.util.Objects;
+
+public class SpecInputModel {
+
+    private final InputStream inputStream;
+    private final String filename;
+
+    public SpecInputModel(final String filename, final InputStream inputStream) {
+        requireNonNull(inputStream, "InputStream can't be null");
+        requireNonNull(filename, "File name can't be null");
+        this.inputStream = inputStream;
+        this.filename = filename;
+    }
+
+    public String getFileName() {
+        return filename;
+    }
+
+    public InputStream getInputStream() {
+        return inputStream;
+    }
+
+    @Override
+    public String toString() {
+        return "SpecInputModel{" +
+                "name='" + filename + '\'' +
+                '}';
+    }
+
+    @Override
+    public boolean equals(Object o) {
+        if (this == o) {
+            return true;
+        }
+        if (o == null || getClass() != o.getClass()) {
+            return false;
+        }
+        SpecInputModel that = (SpecInputModel) o;
+        return inputStream.equals(that.inputStream) && filename.equals(that.filename);
+    }
+
+    @Override
+    public int hashCode() {
+        return Objects.hash(inputStream, filename);
+    }
+}