feat(core): add api-resources schema command for JSON Schema generation

Add getResourceSchema() to JikkouApi to generate JSON Schema for any
registered resource type. Includes CLI command, API server endpoint,
and API client support.

Author: fhussonnois

cli/src/main/java/io/streamthoughts/jikkou/client/Jikkou.java

@@ -34,7 +34,7 @@
 import io.streamthoughts.jikkou.client.command.reconcile.PatchResourceCommand;
 import io.streamthoughts.jikkou.client.command.reconcile.ReplaceResourceCommand;
 import io.streamthoughts.jikkou.client.command.reconcile.UpdateResourceCommand;
-import io.streamthoughts.jikkou.client.command.resources.ListApiResourcesCommand;
+import io.streamthoughts.jikkou.client.command.resources.ApiResourceCommand;
 import io.streamthoughts.jikkou.client.command.server.ServerInfoCommand;
 import io.streamthoughts.jikkou.client.command.validate.ValidateCommand;
 import io.streamthoughts.jikkou.client.context.ConfigurationContext;
@@ -88,7 +88,7 @@
         ReplaceResourceCommand.class,
         ApiExtensionCommand.class,
         ApiProviderCommand.class,
-        ListApiResourcesCommand.class,
+        ApiResourceCommand.class,
         ConfigCommand.class,
         DiffCommand.class,
         PrepareCommand.class,

cli/src/main/java/io/streamthoughts/jikkou/client/command/resources/ApiResourceCommand.java

@@ -0,0 +1,23 @@
+/*
+ * SPDX-License-Identifier: Apache-2.0
+ * Copyright (c) The original authors
+ *
+ * Licensed under the Apache Software License version 2.0, available at http://www.apache.org/licenses/LICENSE-2.0
+ */
+package io.streamthoughts.jikkou.client.command.resources;
+
+import io.streamthoughts.jikkou.client.command.CLIBaseCommand;
+import jakarta.inject.Singleton;
+import picocli.CommandLine.Command;
+
+@Command(name = "api-resources",
+        header = "Print the supported API resources",
+        description = {
+                "List and describe the API resources supported by the Jikkou CLI or Jikkou API Server (in proxy mode)."
+        },
+        subcommands = {
+                ListApiResourcesCommand.class,
+                GetApiResourceSchemaCommand.class,
+        })
+@Singleton
+public class ApiResourceCommand extends CLIBaseCommand {}

cli/src/main/java/io/streamthoughts/jikkou/client/command/resources/GetApiResourceSchemaCommand.java

@@ -0,0 +1,54 @@
+/*
+ * SPDX-License-Identifier: Apache-2.0
+ * Copyright (c) The original authors
+ *
+ * Licensed under the Apache Software License version 2.0, available at http://www.apache.org/licenses/LICENSE-2.0
+ */
+package io.streamthoughts.jikkou.client.command.resources;
+
+import io.streamthoughts.jikkou.client.command.CLIBaseCommand;
+import io.streamthoughts.jikkou.core.JikkouApi;
+import io.streamthoughts.jikkou.core.io.Jackson;
+import io.streamthoughts.jikkou.core.models.ApiResourceSchema;
+import io.streamthoughts.jikkou.core.models.ResourceType;
+import jakarta.inject.Inject;
+import jakarta.inject.Singleton;
+import java.util.concurrent.Callable;
+import picocli.CommandLine;
+import picocli.CommandLine.Command;
+import picocli.CommandLine.Option;
+
+@Command(name = "schema",
+        header = "Print the JSON Schema of a resource type",
+        description = "Get the JSON Schema for a specific API resource type."
+)
+@Singleton
+public class GetApiResourceSchemaCommand extends CLIBaseCommand implements Callable<Integer> {
+
+    @Option(names = {"--api-version"},
+            required = true,
+            description = "The API version of the resource (e.g., 'kafka.jikkou.io/v1')."
+    )
+    public String apiVersion;
+
+    @Option(names = {"--kind"},
+            required = true,
+            description = "The kind of the resource (e.g., 'KafkaTopic')."
+    )
+    public String kind;
+
+    @Inject
+    private JikkouApi api;
+
+    /** {@inheritDoc} **/
+    @Override
+    public Integer call() throws Exception {
+        ResourceType resourceType = ResourceType.of(kind, apiVersion);
+        ApiResourceSchema schema = api.getResourceSchema(resourceType);
+        String json = Jackson.JSON_OBJECT_MAPPER
+                .writerWithDefaultPrettyPrinter()
+                .writeValueAsString(schema.schema());
+        System.out.println(json);
+        return CommandLine.ExitCode.OK;
+    }
+}

cli/src/main/java/io/streamthoughts/jikkou/client/command/resources/ListApiResourcesCommand.java

@@ -29,7 +29,7 @@
 import picocli.CommandLine.Mixin;
 import picocli.CommandLine.Option;
 
-@Command(name = "api-resources",
+@Command(name = "list",
         header = "Print the supported API resources",
         description = "List the API resources supported by the Jikkou CLI or Jikkou API Server (in proxy mode)."
 )

cli/src/test/java/io/streamthoughts/jikkou/client/JikkouTest.java

@@ -35,7 +35,7 @@ void shouldReturnUsageCodeForNoArgs() {
 
     @Test
     void shouldPrintApiResources() {
-        int execute = Jikkou.execute(new String[]{"api-resources"});
+        int execute = Jikkou.execute(new String[]{"api-resources", "list"});
         Assertions.assertEquals(CommandLine.ExitCode.OK, execute);
     }
 

core/pom.xml

@@ -87,6 +87,14 @@
             <artifactId>avro</artifactId>
             <version>${avro.version}</version>
         </dependency>
+        <dependency>
+            <groupId>com.github.victools</groupId>
+            <artifactId>jsonschema-generator</artifactId>
+        </dependency>
+        <dependency>
+            <groupId>com.github.victools</groupId>
+            <artifactId>jsonschema-module-jackson</artifactId>
+        </dependency>
     </dependencies>
 
 </project>

core/src/main/java/io/streamthoughts/jikkou/core/DefaultApi.java

@@ -41,6 +41,7 @@
 import io.streamthoughts.jikkou.core.models.ApiResource;
 import io.streamthoughts.jikkou.core.models.ApiResourceChangeList;
 import io.streamthoughts.jikkou.core.models.ApiResourceList;
+import io.streamthoughts.jikkou.core.models.ApiResourceSchema;
 import io.streamthoughts.jikkou.core.models.ApiResourceVerbOptionList;
 import io.streamthoughts.jikkou.core.models.ApiValidationResult;
 import io.streamthoughts.jikkou.core.models.CoreAnnotations;
@@ -64,6 +65,7 @@
 import io.streamthoughts.jikkou.core.reconciler.ResourceChangeFilter;
 import io.streamthoughts.jikkou.core.reconciler.config.ApiOptionSpecFactory;
 import io.streamthoughts.jikkou.core.reporter.CombineChangeReporter;
+import io.streamthoughts.jikkou.core.resource.JacksonResourceSchemaGenerator;
 import io.streamthoughts.jikkou.core.resource.ResourceDescriptor;
 import io.streamthoughts.jikkou.core.resource.ResourceRegistry;
 import io.streamthoughts.jikkou.core.selector.Selector;
@@ -149,6 +151,21 @@ private DefaultApi(@NotNull final ExtensionFactory extensionFactory,
         this.resourceRegistry = Objects.requireNonNull(resourceRegistry, "resourceRegistry must not be null");
     }
 
+    /**
+     * {@inheritDoc}
+     **/
+    @Override
+    public ApiResourceSchema getResourceSchema(@NotNull ResourceType resourceType) {
+        ResourceDescriptor descriptor = resourceRegistry.findDescriptorByType(resourceType)
+                .orElseThrow(() -> new ResourceNotFoundException(
+                        String.format("No resource found for type: apiVersion='%s', kind='%s'",
+                                resourceType.apiVersion(), resourceType.kind())));
+        JacksonResourceSchemaGenerator generator = new JacksonResourceSchemaGenerator();
+        com.fasterxml.jackson.databind.JsonNode schema = generator.generate(descriptor.resourceClass());
+        String groupVersion = resourceType.group() + GROUP_API_VERSION_SEPARATOR + resourceType.apiVersion();
+        return new ApiResourceSchema(groupVersion, resourceType.kind(), schema);
+    }
+
     /**
      * {@inheritDoc}
      **/

core/src/main/java/io/streamthoughts/jikkou/core/JikkouApi.java

@@ -26,6 +26,7 @@
 import io.streamthoughts.jikkou.core.models.ApiProviderList;
 import io.streamthoughts.jikkou.core.models.ApiResourceChangeList;
 import io.streamthoughts.jikkou.core.models.ApiResourceList;
+import io.streamthoughts.jikkou.core.models.ApiResourceSchema;
 import io.streamthoughts.jikkou.core.models.ApiValidationResult;
 import io.streamthoughts.jikkou.core.models.HasItems;
 import io.streamthoughts.jikkou.core.models.HasMetadata;
@@ -170,6 +171,17 @@ <T extends Extension> B register(@NotNull Class<T> type,
     ApiResourceList listApiResources(@NotNull String group,
                                      @NotNull String version);
 
+    /**
+     * Gets the JSON Schema for the specified resource type.
+     *
+     * @param resourceType the resource type.
+     * @return an {@link ApiResourceSchema} containing the JSON Schema.
+     * @throws io.streamthoughts.jikkou.core.exceptions.ResourceNotFoundException
+     *         if no resource is registered for the given type.
+     * @since 0.38.0
+     */
+    ApiResourceSchema getResourceSchema(@NotNull ResourceType resourceType);
+
     /**
      * List the supported API groups.
      *

core/src/main/java/io/streamthoughts/jikkou/core/models/ApiResourceSchema.java

@@ -0,0 +1,28 @@
+/*
+ * SPDX-License-Identifier: Apache-2.0
+ * Copyright (c) The original authors
+ *
+ * Licensed under the Apache Software License version 2.0, available at http://www.apache.org/licenses/LICENSE-2.0
+ */
+package io.streamthoughts.jikkou.core.models;
+
+import com.fasterxml.jackson.annotation.JsonProperty;
+import com.fasterxml.jackson.annotation.JsonPropertyOrder;
+import com.fasterxml.jackson.databind.JsonNode;
+import io.streamthoughts.jikkou.core.annotation.Reflectable;
+
+/**
+ * Represents the JSON Schema for a resource type.
+ *
+ * @param apiVersion the API version of the resource.
+ * @param kind       the kind of the resource.
+ * @param schema     the JSON Schema.
+ * @since 0.38.0
+ */
+@Reflectable
+@JsonPropertyOrder({"apiVersion", "kind", "schema"})
+public record ApiResourceSchema(
+        @JsonProperty("apiVersion") String apiVersion,
+        @JsonProperty("kind") String kind,
+        @JsonProperty("schema") JsonNode schema
+) {}

core/src/main/java/io/streamthoughts/jikkou/core/resource/ResourceSchemaGenerator.java

@@ -0,0 +1,25 @@
+/*
+ * SPDX-License-Identifier: Apache-2.0
+ * Copyright (c) The original authors
+ *
+ * Licensed under the Apache Software License version 2.0, available at http://www.apache.org/licenses/LICENSE-2.0
+ */
+package io.streamthoughts.jikkou.core.resource;
+
+import com.fasterxml.jackson.databind.JsonNode;
+import io.streamthoughts.jikkou.core.models.Resource;
+import org.jetbrains.annotations.NotNull;
+
+/**
+ * Generates a JSON Schema for a given resource class.
+ */
+public interface ResourceSchemaGenerator {
+
+    /**
+     * Generates a JSON Schema for the specified resource class.
+     *
+     * @param resourceClass the resource class.
+     * @return a {@link JsonNode} representing the JSON Schema.
+     */
+    JsonNode generate(@NotNull Class<? extends Resource> resourceClass);
+}