feat(core): document deprecated tasks (#1078)

kestra-io · Mar 17, 2023 · 3105ec2 · 3105ec2
1 parent 8475950
commit 3105ec2
Show file tree

Hide file tree

Showing 6 changed files with 47 additions and 5 deletions.
diff --git a/core/src/main/java/io/kestra/core/docs/ClassPluginDocumentation.java b/core/src/main/java/io/kestra/core/docs/ClassPluginDocumentation.java
@@ -14,6 +14,7 @@
 @ToString
 @NoArgsConstructor
 public class ClassPluginDocumentation<T> {
+    private Boolean deprecated;
     private String cls;
     private String icon;
     private String group;
@@ -72,6 +73,7 @@ private ClassPluginDocumentation(JsonSchemaGenerator jsonSchemaGenerator, Regist
 
         this.docDescription = this.propertiesSchema.containsKey("title") ? (String) this.propertiesSchema.get("title") : null;
         this.docBody = this.propertiesSchema.containsKey("description") ? (String) this.propertiesSchema.get("description") : null;
+        this.deprecated = this.propertiesSchema.containsKey("$deprecated");
 
         if (this.propertiesSchema.containsKey("$examples")) {
             List<Map<String, Object>> examples = (List<Map<String, Object>>) this.propertiesSchema.get("$examples");

diff --git a/core/src/main/java/io/kestra/core/docs/JsonSchemaGenerator.java b/core/src/main/java/io/kestra/core/docs/JsonSchemaGenerator.java
@@ -239,7 +239,6 @@ public CustomDefinition provideCustomSchemaDefinition(ResolvedType javaType, Sch
                 memberAttributes.put("$dynamic", pluginPropertyAnnotation.dynamic());
             }
 
-
             Schema schema = member.getAnnotationConsideringFieldAndGetter(Schema.class);
             if (schema != null && schema.deprecated()) {
                 memberAttributes.put("$deprecated", true);
@@ -279,6 +278,13 @@ public CustomDefinition provideCustomSchemaDefinition(ResolvedType javaType, Sch
                         collectedTypeAttributes.set("$metrics", context.getGeneratorConfig().createArrayNode().addAll(metrics));
                     }
                 }
+
+                // handle deprecated tasks
+                Schema schema = scope.getType().getErasedType().getAnnotation(Schema.class);
+                Deprecated deprecated = scope.getType().getErasedType().getAnnotation(Deprecated.class);
+                if ((schema != null && schema.deprecated()) || deprecated != null ) {
+                    collectedTypeAttributes.put("$deprecated", "true");
+                }
             });
 
         // PluginProperty additionalProperties
@@ -510,6 +516,9 @@ private void addMainRefProperties(JsonNode mainClassDef, ObjectNode objectNode)
         if (mainClassDef.has("$metrics")) {
             objectNode.set("$metrics", mainClassDef.get("$metrics"));
         }
+        if (mainClassDef.has("$deprecated")) {
+            objectNode.set("$deprecated", mainClassDef.get("$deprecated"));
+        }
     }
 
     private Object buildDefaultInstance(Class<?> cls) {

diff --git a/core/src/main/java/io/kestra/core/tasks/debugs/Echo.java b/core/src/main/java/io/kestra/core/tasks/debugs/Echo.java
@@ -22,9 +22,9 @@
 @Getter
 @NoArgsConstructor
 @Schema(
-    title = "Debugging task that logs a rendered value.",
-    description = "This task is mostly useful for debugging purpose.\n\n" +
-        "It allows you to log inputs or outputs variables or to debug some templated functions."
+    title = "Log a message in the task logs.",
+    description = "This task is deprecated, please use the io.kestra.core.tasks.log.Log task instead.",
+    deprecated = true
 )
 @Plugin(
     examples = {

diff --git a/core/src/main/resources/docs/task.hbs b/core/src/main/resources/docs/task.hbs
@@ -109,7 +109,7 @@ icon: {{ icon }}
 {{~/inline~}}
 {{!-- {{                 Main doc                 }} --}}
 <h1>
-    {{#if icon ~}}<img width="25" src="data:image/svg+xml;base64,{{icon}}" alt="{{shortName}}" />{{/if }} {{shortName}}
+    {{#if icon ~}}<img width="25" src="data:image/svg+xml;base64,{{icon}}" alt="{{shortName}}" />{{/if }} {{shortName}} {{~#if deprecated }}- 🔒 Deprecated{{~/if}}
 </h1>
 
 ```yaml

diff --git a/core/src/test/java/io/kestra/core/docs/DocumentationGeneratorTest.java b/core/src/test/java/io/kestra/core/docs/DocumentationGeneratorTest.java
@@ -1,5 +1,6 @@
 package io.kestra.core.docs;
 
+import io.kestra.core.tasks.debugs.Echo;
 import io.kestra.core.tasks.debugs.Return;
 import io.kestra.core.tasks.flows.Flow;
 import io.micronaut.test.extensions.junit5.annotation.MicronautTest;
@@ -91,4 +92,18 @@ void defaultBool() throws IOException {
 
         assertThat(render, containsString("* **Default:** `false`"));
     }
+
+    @Test
+    void echo() throws IOException {
+        PluginScanner pluginScanner = new PluginScanner(ClassPluginDocumentationTest.class.getClassLoader());
+        RegisteredPlugin scan = pluginScanner.scan();
+        Class<Echo> bash = scan.findClass(Echo.class.getName()).orElseThrow();
+
+        ClassPluginDocumentation<? extends Task> doc = ClassPluginDocumentation.of(jsonSchemaGenerator, scan, bash, Task.class);
+
+        String render = DocumentationGenerator.render(doc);
+
+        assertThat(render, containsString("Echo"));
+        assertThat(render, containsString("- \uD83D\uDD12 Deprecated"));
+    }
 }
diff --git a/core/src/test/java/io/kestra/core/docs/JsonSchemaGeneratorTest.java b/core/src/test/java/io/kestra/core/docs/JsonSchemaGeneratorTest.java
@@ -6,6 +6,7 @@
 import io.kestra.core.models.tasks.VoidOutput;
 import io.kestra.core.models.triggers.AbstractTrigger;
 import io.kestra.core.runners.RunContext;
+import io.kestra.core.tasks.debugs.Echo;
 import io.kestra.core.tasks.debugs.Return;
 import io.kestra.core.Helpers;
 import io.swagger.v3.oas.annotations.media.Schema;
@@ -160,6 +161,21 @@ void returnTask() throws URISyntaxException {
         });
     }
 
+    @SuppressWarnings("unchecked")
+    @Test
+    void echoTask() throws URISyntaxException {
+        Helpers.runApplicationContext((applicationContext) -> {
+            JsonSchemaGenerator jsonSchemaGenerator = applicationContext.getBean(JsonSchemaGenerator.class);
+
+            Map<String, Object> returnSchema = jsonSchemaGenerator.schemas(Echo.class);
+            System.out.println(returnSchema);
+            var definitions = (Map<String, Map<String, Object>>) returnSchema.get("definitions");
+            var returnTask = definitions.get("io.kestra.core.tasks.debugs.Echo-1");
+            var deprecated = (String) returnTask.get("$deprecated");
+            assertThat(deprecated, is("true"));
+        });
+    }
+
     @SuppressWarnings("unchecked")
     @Test
     void testEnum() {