From 8ce05b5493c72520a20d61fa1c71247707c423ef Mon Sep 17 00:00:00 2001 From: George Fu Date: Thu, 7 Mar 2024 16:31:46 +0000 Subject: [PATCH] docs: add more information about BLOB values in structures --- .../StructureExampleGenerator.java | 71 ++++++++++++------- 1 file changed, 45 insertions(+), 26 deletions(-) diff --git a/smithy-typescript-codegen/src/main/java/software/amazon/smithy/typescript/codegen/documentation/StructureExampleGenerator.java b/smithy-typescript-codegen/src/main/java/software/amazon/smithy/typescript/codegen/documentation/StructureExampleGenerator.java index cd5a99f213c..d20c42a4acc 100644 --- a/smithy-typescript-codegen/src/main/java/software/amazon/smithy/typescript/codegen/documentation/StructureExampleGenerator.java +++ b/smithy-typescript-codegen/src/main/java/software/amazon/smithy/typescript/codegen/documentation/StructureExampleGenerator.java @@ -22,6 +22,7 @@ import software.amazon.smithy.model.shapes.Shape; import software.amazon.smithy.model.shapes.StructureShape; import software.amazon.smithy.model.shapes.UnionShape; +import software.amazon.smithy.model.traits.InputTrait; import software.amazon.smithy.model.traits.RequiredTrait; import software.amazon.smithy.model.traits.StreamingTrait; @@ -32,7 +33,7 @@ public abstract class StructureExampleGenerator { /** * Generates an example structure for API documentation, as an * automated gap filler for operations that do not have - * hand written examples. + * handwritten examples. * * Example for Athena::createPreparedStatement * ```js @@ -46,7 +47,8 @@ public abstract class StructureExampleGenerator { */ public static String generateStructuralHintDocumentation(Shape shape, Model model, boolean isComment) { StringBuilder buffer = new StringBuilder(); - shape(shape, buffer, model, 0, new ShapeTracker()); + boolean isInput = shape.hasTrait(InputTrait.class); + shape(shape, buffer, model, 0, new ShapeTracker(), isInput); // replace non-leading whitespace with single space. String s = Arrays.stream( @@ -62,10 +64,12 @@ public static String generateStructuralHintDocumentation(Shape shape, Model mode } private static void structure(StructureShape structureShape, - StringBuilder buffer, Model model, - int indentation, - ShapeTracker shapeTracker) { - if (structureShape.getAllMembers().size() == 0) { + StringBuilder buffer, + Model model, + int indentation, + ShapeTracker shapeTracker, + boolean isInput) { + if (structureShape.getAllMembers().isEmpty()) { append(indentation, buffer, "{},"); checkRequired(indentation, buffer, structureShape); } else { @@ -76,33 +80,35 @@ private static void structure(StructureShape structureShape, checkRequired(indentation, buffer, structureShape); structureShape.getAllMembers().values().forEach(member -> { append(indentation + 2, buffer, member.getMemberName() + ": "); - shape(member, buffer, model, indentation + 2, shapeTracker); + shape(member, buffer, model, indentation + 2, shapeTracker, isInput); }); append(indentation, buffer, "},\n"); } } private static void union(UnionShape unionShape, - StringBuilder buffer, - Model model, - int indentation, - ShapeTracker shapeTracker) { + StringBuilder buffer, + Model model, + int indentation, + ShapeTracker shapeTracker, + boolean isInput) { append(indentation, buffer, "{" + (shapeTracker.getOccurrenceCount(unionShape) == 1 ? " // " + unionShape.getId().getName() : "// ") + " Union: only one key present"); checkRequired(indentation, buffer, unionShape); unionShape.getAllMembers().values().forEach(member -> { append(indentation + 2, buffer, member.getMemberName() + ": "); - shape(member, buffer, model, indentation + 2, shapeTracker); + shape(member, buffer, model, indentation + 2, shapeTracker, isInput); }); append(indentation, buffer, "},\n"); } private static void shape(Shape shape, - StringBuilder buffer, - Model model, - int indentation, - ShapeTracker shapeTracker) { + StringBuilder buffer, + Model model, + int indentation, + ShapeTracker shapeTracker, + boolean isInput) { Shape target; if (shape instanceof MemberShape) { target = model.getShape(((MemberShape) shape).getTarget()).get(); @@ -123,17 +129,30 @@ private static void shape(Shape shape, append(indentation, buffer, "Number(\"bigint\"),"); break; case BLOB: - if (target.hasTrait(StreamingTrait.class)) { - append(indentation, buffer, "\"STREAMING_BLOB_VALUE\","); + if (isInput) { + if (target.hasTrait(StreamingTrait.class)) { + append(indentation, buffer, + "\"MULTIPLE_TYPES_ACCEPTED\", // see @smithy/types -> StreamingBlobPayloadInputTypes"); + } else { + append(indentation, buffer, + """ + new Uint8Array(), // e.g. Buffer.from("") or new TextEncoder().encode("")"""); + } } else { - append(indentation, buffer, "\"BLOB_VALUE\","); + if (target.hasTrait(StreamingTrait.class)) { + append(indentation, buffer, + "\"\", // see @smithy/types -> StreamingBlobPayloadOutputTypes"); + } else { + append(indentation, buffer, + "new Uint8Array(),"); + } } break; case BOOLEAN: append(indentation, buffer, "true || false,"); break; case BYTE: - append(indentation, buffer, "\"BYTE_VALUE\","); + append(indentation, buffer, "0, // BYTE_VALUE"); break; case DOCUMENT: append(indentation, buffer, "\"DOCUMENT_VALUE\","); @@ -167,7 +186,7 @@ private static void shape(Shape shape, : "")); checkRequired(indentation, buffer, shape); ListShape list = (ListShape) target; - shape(list.getMember(), buffer, model, indentation + 2, shapeTracker); + shape(list.getMember(), buffer, model, indentation + 2, shapeTracker, isInput); append(indentation, buffer, "],\n"); break; case MAP: @@ -178,17 +197,17 @@ private static void shape(Shape shape, append(indentation + 2, buffer, "\"\": "); MapShape map = (MapShape) target; shape(model.getShape(map.getValue().getTarget()).get(), buffer, model, indentation + 2, - shapeTracker); + shapeTracker, isInput); append(indentation, buffer, "},\n"); break; case STRUCTURE: StructureShape structure = (StructureShape) target; - structure(structure, buffer, model, indentation, shapeTracker); + structure(structure, buffer, model, indentation, shapeTracker, isInput); break; case UNION: UnionShape union = (UnionShape) target; - union(union, buffer, model, indentation, shapeTracker); + union(union, buffer, model, indentation, shapeTracker, isInput); break; case ENUM: @@ -272,8 +291,8 @@ private static void append(int indentation, StringBuilder buffer, String tail) { * This handles the case of recursive shapes. */ private static class ShapeTracker { - private Map> depths = new HashMap>(); - private Map occurrences = new HashMap(); + private final Map> depths = new HashMap<>(); + private final Map occurrences = new HashMap<>(); /** * Mark that a shape is observed at depth.