From 61ff65cc1ef1273f5d8508e91ddb9b74871a2e24 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Lo=C3=AFc=20Mathieu?= Date: Fri, 17 Mar 2023 15:15:11 +0100 Subject: [PATCH] feat(core): document deprecated tasks --- .../core/docs/ClassPluginDocumentation.java | 2 ++ .../io/kestra/core/docs/JsonSchemaGenerator.java | 11 ++++++++++- .../java/io/kestra/core/tasks/debugs/Echo.java | 6 +++--- core/src/main/resources/docs/task.hbs | 2 +- .../core/docs/DocumentationGeneratorTest.java | 15 +++++++++++++++ .../core/docs/JsonSchemaGeneratorTest.java | 16 ++++++++++++++++ 6 files changed, 47 insertions(+), 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 index a816a4d2f4d..4dc30506908 100644 --- 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 { + 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> examples = (List>) 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 index 6a84b43d470..88c22c97182 100644 --- 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 index ff258933818..89038496ec6 100644 --- 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 index 97ae7e9804f..acac942f78a 100644 --- 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 }} --}}

- {{#if icon ~}}{{shortName}}{{/if }} {{shortName}} + {{#if icon ~}}{{shortName}}{{/if }} {{shortName}} {{~#if deprecated }}- 🔒 Deprecated{{~/if}}

```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 index cebcf6d43d7..1c24259103d 100644 --- 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 bash = scan.findClass(Echo.class.getName()).orElseThrow(); + + ClassPluginDocumentation 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 index 911cb14ffc3..8ab5ee7efe1 100644 --- 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 returnSchema = jsonSchemaGenerator.schemas(Echo.class); + System.out.println(returnSchema); + var definitions = (Map>) 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() {