Generate examples

This adds support for the examples trait to javadoc generation
for clients.

Author: JordonPhillips

codegen/codegen-core/src/main/java/software/amazon/smithy/java/codegen/writer/JavaWriter.java

@@ -59,6 +59,20 @@ private void addImport(Symbol symbol) {
         addImport(symbol, symbol.getName());
     }
 
+    /**
+     * @return Returns the namespace that the file being written is contained within.
+     */
+    public String getPackageNamespace() {
+        return packageNamespace;
+    }
+
+    /**
+     * @return Returns the name of the file being written to.
+     */
+    public String getFilename() {
+        return filename;
+    }
+
     @Override
     public String toString() {
         // Do not add headers or attempt symbol resolution for resource files

codegen/plugins/client-codegen/src/main/java/software/amazon/smithy/java/codegen/client/integrations/javadoc/ClientJavadocExamplesIntegration.java

@@ -0,0 +1,44 @@
+/*
+ * Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved.
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+package software.amazon.smithy.java.codegen.client.integrations.javadoc;
+
+import java.util.List;
+import software.amazon.smithy.java.codegen.CodeGenerationContext;
+import software.amazon.smithy.java.codegen.JavaCodegenIntegration;
+import software.amazon.smithy.java.codegen.writer.JavaWriter;
+import software.amazon.smithy.utils.CodeInterceptor;
+import software.amazon.smithy.utils.CodeSection;
+import software.amazon.smithy.utils.SmithyInternalApi;
+
+/**
+ * Adds client examples to the generated Javadoc.
+ */
+@SmithyInternalApi
+public class ClientJavadocExamplesIntegration implements JavaCodegenIntegration {
+
+    @Override
+    public String name() {
+        return "client-javadoc-examples";
+    }
+
+    @Override
+    public List<String> runBefore() {
+        // The DocumentationTrait interceptor uses "prepend", and the finalizing formatter
+        // wholly replaces the contents of the JavaDoc section with a formatted version.
+        // By running before the "javadoc" plugin, which includes those interceptors,
+        // we can be sure that what we write will appear after the docs from the doc trait
+        // and will still benefit from formatting.
+        return List.of("javadoc");
+    }
+
+    @Override
+    public List<? extends CodeInterceptor<? extends CodeSection, JavaWriter>> interceptors(
+            CodeGenerationContext codegenContext
+    ) {
+        return List.of(new ExamplesTraitInterceptor(codegenContext));
+    }
+
+}

codegen/plugins/client-codegen/src/main/java/software/amazon/smithy/java/codegen/client/integrations/javadoc/ExamplesTraitInterceptor.java

@@ -0,0 +1,139 @@
+/*
+ * Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved.
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+package software.amazon.smithy.java.codegen.client.integrations.javadoc;
+
+import java.nio.file.Paths;
+import software.amazon.smithy.codegen.core.CodegenException;
+import software.amazon.smithy.java.codegen.CodeGenerationContext;
+import software.amazon.smithy.java.codegen.CodegenUtils;
+import software.amazon.smithy.java.codegen.generators.SnippetGenerator;
+import software.amazon.smithy.java.codegen.sections.JavadocSection;
+import software.amazon.smithy.java.codegen.writer.JavaWriter;
+import software.amazon.smithy.model.shapes.OperationShape;
+import software.amazon.smithy.model.shapes.ServiceShape;
+import software.amazon.smithy.model.traits.ExamplesTrait;
+import software.amazon.smithy.utils.CodeInterceptor;
+import software.amazon.smithy.utils.StringUtils;
+
+/**
+ * Adds Javadoc examples to operations with the examples trait.
+ */
+public class ExamplesTraitInterceptor implements CodeInterceptor.Appender<JavadocSection, JavaWriter> {
+
+    private final CodeGenerationContext context;
+
+    public ExamplesTraitInterceptor(CodeGenerationContext context) {
+        this.context = context;
+    }
+
+    @Override
+    public void append(JavaWriter writer, JavadocSection section) {
+        var operation = section.targetedShape()
+                .asOperationShape()
+                .orElseThrow(() -> new CodegenException(String.format(
+                        "Expected shape to be an operation shape, but was " + section.targetedShape().getType())));
+        var trait = section.targetedShape().expectTrait(ExamplesTrait.class);
+        writer.pushState();
+
+        var operationSymbol = context.symbolProvider().toSymbol(operation);
+
+        // The effective heading levels are different if the documentation is being put
+        // in the operation's generated class docs or the client's generated method docs,
+        // so this checks to see which file we're in and adjusts the heading level
+        // accordingly.
+        var operationFile = Paths.get(operationSymbol.getDefinitionFile()).normalize();
+        var activeFile = Paths.get(writer.getFilename()).normalize();
+        if (operationFile.equals(activeFile)) {
+            writer.putContext("sectionHeading", "h2");
+            writer.putContext("titleHeading", "h3");
+        } else {
+            writer.putContext("sectionHeading", "h4");
+            writer.putContext("titleHeading", "h5");
+        }
+
+        writer.write("<${sectionHeading:L}>Examples</${sectionHeading:L}>");
+        for (ExamplesTrait.Example example : trait.getExamples()) {
+            writer.pushState();
+            writer.putContext("docs", example.getDocumentation().orElse(null));
+            writer.putContext("title", example.getTitle());
+            writer.write("""
+                    <${titleHeading:L}>${title:L}</${titleHeading:L}>
+
+                    ${?docs}<p>${docs:L}
+                    ${/docs}
+                    <pre>
+                    {@code
+                    ${C|}
+                    }
+                    </pre>
+                    """, writer.consumer(w -> writeExampleSnippet(writer, operation, example)));
+            writer.popState();
+        }
+        writer.popState();
+    }
+
+    // TODO: collect these and write them out to a shared snippets file
+    private void writeExampleSnippet(JavaWriter writer, OperationShape operation, ExamplesTrait.Example example) {
+        var service = context.model().expectShape(context.settings().service(), ServiceShape.class);
+        var operationName = StringUtils.uncapitalize(CodegenUtils.getDefaultName(operation, service));
+        writer.putContext("operationName", operationName);
+
+        var inputShape = context.model().expectShape(operation.getInputShape());
+        writer.putContext(
+                "input",
+                SnippetGenerator.generateShapeInitializer(context, inputShape, example.getInput()));
+
+        if (example.getOutput().isPresent() && !example.getOutput().get().isEmpty()) {
+            var outputShape = context.model().expectShape(operation.getOutputShape());
+            writer.putContext(
+                    "output",
+                    SnippetGenerator.generateShapeInitializer(context, outputShape, example.getOutput().get()));
+        } else {
+            writer.putContext("output", null);
+        }
+
+        if (example.getError().isPresent()) {
+            writer.putContext("hasError", true);
+            var error = example.getError().get();
+            var errorShape = context.model().expectShape(error.getShapeId());
+            writer.putContext(
+                    "error",
+                    SnippetGenerator.generateShapeInitializer(context, errorShape, error.getContent()));
+            writer.putContext("errorSymbol", context.symbolProvider().toSymbol(errorShape));
+        } else {
+            writer.putContext("hasError", false);
+        }
+
+        writer.writeInline("""
+                var input = ${input:L|};
+                ${?hasError}
+
+                try {
+                    client.${operationName:L}(input);
+                } catch (${errorSymbol:T} e) {
+                    e.equals(${error:L|});
+                }
+                ${/hasError}
+                ${^hasError}
+
+                var result = client.${operationName:L}(input);
+                result.equals(${output:L|});
+                ${/hasError}""");
+    }
+
+    @Override
+    public Class<JavadocSection> sectionType() {
+        return JavadocSection.class;
+    }
+
+    @Override
+    public boolean isIntercepted(JavadocSection section) {
+        // The examples trait can only be applied to operations for now,
+        // but we add an explicit check anyway in case it ever gets expanded.
+        var shape = section.targetedShape();
+        return shape.hasTrait(ExamplesTrait.class) && shape.isOperationShape();
+    }
+}

codegen/plugins/client-codegen/src/main/resources/META-INF/services/software.amazon.smithy.java.codegen.JavaCodegenIntegration

@@ -0,0 +1 @@
+software.amazon.smithy.java.codegen.client.integrations.javadoc.ClientJavadocExamplesIntegration

codegen/plugins/client-codegen/src/test/java/software/amazon/smithy/java/codegen/client/integrations/javadoc/ClientJavadocExamplesIntegrationTest.java

@@ -0,0 +1,63 @@
+/*
+ * Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved.
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+package software.amazon.smithy.java.codegen.client.integrations.javadoc;
+
+import static org.hamcrest.MatcherAssert.assertThat;
+import static org.hamcrest.Matchers.containsString;
+
+import java.net.URL;
+import java.util.Objects;
+import org.junit.jupiter.api.Test;
+import software.amazon.smithy.java.codegen.client.utils.AbstractCodegenFileTest;
+
+public class ClientJavadocExamplesIntegrationTest extends AbstractCodegenFileTest {
+    private static final URL TEST_FILE = Objects.requireNonNull(
+            ClientJavadocExamplesIntegrationTest.class.getResource("javadoc-examples.smithy"));
+
+    @Override
+    protected URL testFile() {
+        return TEST_FILE;
+    }
+
+    @Test
+    void includesExamples() {
+        var fileContents = getFileStringForClass("client/TestServiceClient");
+        var expected = """
+                     * <h4>Examples</h4>
+                     * <h5>Basic Example</h5>
+                     * <pre>
+                     * {@code
+                     * var input = ExamplesOperationInput.builder()
+                     *                 .foo("foo")
+                     *                 .build();
+                     *
+                     * var result = client.examplesOperation(input);
+                     * result.equals(ExamplesOperationOutput.builder()
+                     *                   .bar("bar")
+                     *                   .build());
+                     * }
+                     * </pre>
+                     *
+                     * <h5>Error Example</h5>
+                     * <pre>
+                     * {@code
+                     * var input = ExamplesOperationInput.builder()
+                     *                 .foo("bar")
+                     *                 .build();
+                     *
+                     * try {
+                     *     client.examplesOperation(input);
+                     * } catch (ExampleError e) {
+                     *     e.equals(ExampleError.builder()
+                     *                  .message("bar")
+                     *                  .build());
+                     * }
+                     * }
+                     * </pre>
+                """;
+        assertThat(fileContents, containsString(expected));
+    }
+}

codegen/plugins/client-codegen/src/test/java/software/amazon/smithy/java/codegen/client/utils/AbstractCodegenFileTest.java

@@ -0,0 +1,56 @@
+/*
+ * Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved.
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+package software.amazon.smithy.java.codegen.client.utils;
+
+import static org.junit.jupiter.api.Assertions.assertFalse;
+import static org.junit.jupiter.api.Assertions.assertTrue;
+
+import java.net.URL;
+import java.nio.file.Paths;
+import org.junit.jupiter.api.BeforeEach;
+import software.amazon.smithy.build.MockManifest;
+import software.amazon.smithy.build.PluginContext;
+import software.amazon.smithy.build.SmithyBuildPlugin;
+import software.amazon.smithy.java.codegen.client.JavaClientCodegenPlugin;
+import software.amazon.smithy.model.Model;
+import software.amazon.smithy.model.node.ObjectNode;
+
+public abstract class AbstractCodegenFileTest {
+
+    protected final MockManifest manifest = new MockManifest();
+    protected final SmithyBuildPlugin plugin = new JavaClientCodegenPlugin();
+
+    @BeforeEach
+    public void setup() {
+        var model = Model.assembler()
+                .addImport(testFile())
+                .assemble()
+                .unwrap();
+        var context = PluginContext.builder()
+                .fileManifest(manifest)
+                .settings(settings())
+                .model(model)
+                .build();
+        plugin.execute(context);
+        assertFalse(manifest.getFiles().isEmpty());
+    }
+
+    protected abstract URL testFile();
+
+    protected ObjectNode settings() {
+        return ObjectNode.builder()
+                .withMember("service", "smithy.java.codegen#TestService")
+                .withMember("namespace", "test.smithy.codegen")
+                .build();
+    }
+
+    protected String getFileStringForClass(String className) {
+        var fileStringOptional = manifest.getFileString(
+                Paths.get(String.format("/test/smithy/codegen/%s.java", className)));
+        assertTrue(fileStringOptional.isPresent());
+        return fileStringOptional.get();
+    }
+}

codegen/plugins/client-codegen/src/test/resources/software/amazon/smithy/java/codegen/client/integrations/javadoc/javadoc-examples.smithy

@@ -0,0 +1,48 @@
+$version: "2"
+
+namespace smithy.java.codegen
+
+service TestService {
+    operations: [
+        ExamplesOperation
+    ]
+}
+
+@error("server")
+structure ExampleError {
+    message: String
+}
+
+/// Base docs
+@examples([
+    {
+        title: "Basic Example"
+        input: {
+            foo: "foo"
+        }
+        output: {
+            bar: "bar"
+        }
+    }
+    {
+        title: "Error Example"
+        input: {
+            foo: "bar"
+        }
+        error: {
+            shapeId: ExampleError
+            content: {
+                message: "bar"
+            }
+        }
+    }
+])
+operation ExamplesOperation {
+    input := {
+        foo: String
+    }
+    output := {
+        bar: String
+    }
+    errors: [ExampleError]
+}