Skip to content

Commit

Permalink
docs: add more information about BLOB values in structures
Browse files Browse the repository at this point in the history
  • Loading branch information
@kuhe
kuhe committed Mar 7, 2024
1 parent 85a275d commit 8ce05b5
Showing 1 changed file with 45 additions and 26 deletions.
71 changes: 45 additions & 26 deletions ...va/software/amazon/smithy/typescript/codegen/documentation/StructureExampleGenerator.java
View file
Original file line number Diff line number Diff line change
Expand Up @@ -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;

Expand All @@ -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
Expand All @@ -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(
Expand All @@ -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 {
Expand All @@ -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();
Expand All @@ -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,
"\"<SdkStream>\", // 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\",");
Expand Down Expand Up @@ -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:
Expand All @@ -178,17 +197,17 @@ private static void shape(Shape shape,
append(indentation + 2, buffer, "\"<keys>\": ");
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:
Expand Down Expand Up @@ -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<Shape, Set<Integer>> depths = new HashMap<Shape, Set<Integer>>();
private Map<Shape, Integer> occurrences = new HashMap<Shape, Integer>();
private final Map<Shape, Set<Integer>> depths = new HashMap<>();
private final Map<Shape, Integer> occurrences = new HashMap<>();

/**
* Mark that a shape is observed at depth.
Expand Down

0 comments on commit 8ce05b5

Please sign in to comment.