Skip to content

Commit 8e4a002

Browse files
kuhekuhe
committed
docs: add more information about BLOB values in structures
1 parent 9275e12 commit 8e4a002

File tree

1 file changed

+45
-26
lines changed

1 file changed

+45
-26
lines changed

‎smithy-typescript-codegen/src/main/java/software/amazon/smithy/typescript/codegen/documentation/StructureExampleGenerator.java

Lines changed: 45 additions & 26 deletions
Original file line numberDiff line numberDiff line change
@@ -22,6 +22,7 @@
2222
import software.amazon.smithy.model.shapes.Shape;
2323
import software.amazon.smithy.model.shapes.StructureShape;
2424
import software.amazon.smithy.model.shapes.UnionShape;
25+
import software.amazon.smithy.model.traits.InputTrait;
2526
import software.amazon.smithy.model.traits.RequiredTrait;
2627
import software.amazon.smithy.model.traits.StreamingTrait;
2728

@@ -32,7 +33,7 @@ public abstract class StructureExampleGenerator {
3233
/**
3334
* Generates an example structure for API documentation, as an
3435
* automated gap filler for operations that do not have
35-
* hand written examples.
36+
* handwritten examples.
3637
*
3738
* Example for Athena::createPreparedStatement
3839
* ```js
@@ -46,7 +47,8 @@ public abstract class StructureExampleGenerator {
4647
*/
4748
public static String generateStructuralHintDocumentation(Shape shape, Model model, boolean isComment) {
4849
StringBuilder buffer = new StringBuilder();
49-
shape(shape, buffer, model, 0, new ShapeTracker());
50+
boolean isInput = shape.hasTrait(InputTrait.class);
51+
shape(shape, buffer, model, 0, new ShapeTracker(), isInput);
5052

5153
// replace non-leading whitespace with single space.
5254
String s = Arrays.stream(
@@ -62,10 +64,12 @@ public static String generateStructuralHintDocumentation(Shape shape, Model mode
6264
}
6365

6466
private static void structure(StructureShape structureShape,
65-
StringBuilder buffer, Model model,
66-
int indentation,
67-
ShapeTracker shapeTracker) {
68-
if (structureShape.getAllMembers().size() == 0) {
67+
StringBuilder buffer,
68+
Model model,
69+
int indentation,
70+
ShapeTracker shapeTracker,
71+
boolean isInput) {
72+
if (structureShape.getAllMembers().isEmpty()) {
6973
append(indentation, buffer, "{},");
7074
checkRequired(indentation, buffer, structureShape);
7175
} else {
@@ -76,33 +80,35 @@ private static void structure(StructureShape structureShape,
7680
checkRequired(indentation, buffer, structureShape);
7781
structureShape.getAllMembers().values().forEach(member -> {
7882
append(indentation + 2, buffer, member.getMemberName() + ": ");
79-
shape(member, buffer, model, indentation + 2, shapeTracker);
83+
shape(member, buffer, model, indentation + 2, shapeTracker, isInput);
8084
});
8185
append(indentation, buffer, "},\n");
8286
}
8387
}
8488

8589
private static void union(UnionShape unionShape,
86-
StringBuilder buffer,
87-
Model model,
88-
int indentation,
89-
ShapeTracker shapeTracker) {
90+
StringBuilder buffer,
91+
Model model,
92+
int indentation,
93+
ShapeTracker shapeTracker,
94+
boolean isInput) {
9095
append(indentation, buffer, "{" + (shapeTracker.getOccurrenceCount(unionShape) == 1
9196
? " // " + unionShape.getId().getName()
9297
: "// ") + " Union: only one key present");
9398
checkRequired(indentation, buffer, unionShape);
9499
unionShape.getAllMembers().values().forEach(member -> {
95100
append(indentation + 2, buffer, member.getMemberName() + ": ");
96-
shape(member, buffer, model, indentation + 2, shapeTracker);
101+
shape(member, buffer, model, indentation + 2, shapeTracker, isInput);
97102
});
98103
append(indentation, buffer, "},\n");
99104
}
100105

101106
private static void shape(Shape shape,
102-
StringBuilder buffer,
103-
Model model,
104-
int indentation,
105-
ShapeTracker shapeTracker) {
107+
StringBuilder buffer,
108+
Model model,
109+
int indentation,
110+
ShapeTracker shapeTracker,
111+
boolean isInput) {
106112
Shape target;
107113
if (shape instanceof MemberShape) {
108114
target = model.getShape(((MemberShape) shape).getTarget()).get();
@@ -123,17 +129,30 @@ private static void shape(Shape shape,
123129
append(indentation, buffer, "Number(\"bigint\"),");
124130
break;
125131
case BLOB:
126-
if (target.hasTrait(StreamingTrait.class)) {
127-
append(indentation, buffer, "\"STREAMING_BLOB_VALUE\",");
132+
if (isInput) {
133+
if (target.hasTrait(StreamingTrait.class)) {
134+
append(indentation, buffer,
135+
"\"MULTIPLE_TYPES_ACCEPTED\", // see \@smithy/types -> StreamingBlobPayloadInputTypes");
136+
} else {
137+
append(indentation, buffer,
138+
"""
139+
new Uint8Array(), // e.g. Buffer.from("") or new TextEncoder().encode("")""");
140+
}
128141
} else {
129-
append(indentation, buffer, "\"BLOB_VALUE\",");
142+
if (target.hasTrait(StreamingTrait.class)) {
143+
append(indentation, buffer,
144+
"\"<SdkStream>\", // see \@smithy/types -> StreamingBlobPayloadOutputTypes");
145+
} else {
146+
append(indentation, buffer,
147+
"new Uint8Array(),");
148+
}
130149
}
131150
break;
132151
case BOOLEAN:
133152
append(indentation, buffer, "true || false,");
134153
break;
135154
case BYTE:
136-
append(indentation, buffer, "\"BYTE_VALUE\",");
155+
append(indentation, buffer, "0, // BYTE_VALUE");
137156
break;
138157
case DOCUMENT:
139158
append(indentation, buffer, "\"DOCUMENT_VALUE\",");
@@ -167,7 +186,7 @@ private static void shape(Shape shape,
167186
: ""));
168187
checkRequired(indentation, buffer, shape);
169188
ListShape list = (ListShape) target;
170-
shape(list.getMember(), buffer, model, indentation + 2, shapeTracker);
189+
shape(list.getMember(), buffer, model, indentation + 2, shapeTracker, isInput);
171190
append(indentation, buffer, "],\n");
172191
break;
173192
case MAP:
@@ -178,17 +197,17 @@ private static void shape(Shape shape,
178197
append(indentation + 2, buffer, "\"<keys>\": ");
179198
MapShape map = (MapShape) target;
180199
shape(model.getShape(map.getValue().getTarget()).get(), buffer, model, indentation + 2,
181-
shapeTracker);
200+
shapeTracker, isInput);
182201
append(indentation, buffer, "},\n");
183202
break;
184203

185204
case STRUCTURE:
186205
StructureShape structure = (StructureShape) target;
187-
structure(structure, buffer, model, indentation, shapeTracker);
206+
structure(structure, buffer, model, indentation, shapeTracker, isInput);
188207
break;
189208
case UNION:
190209
UnionShape union = (UnionShape) target;
191-
union(union, buffer, model, indentation, shapeTracker);
210+
union(union, buffer, model, indentation, shapeTracker, isInput);
192211
break;
193212

194213
case ENUM:
@@ -272,8 +291,8 @@ private static void append(int indentation, StringBuilder buffer, String tail) {
272291
* This handles the case of recursive shapes.
273292
*/
274293
private static class ShapeTracker {
275-
private Map<Shape, Set<Integer>> depths = new HashMap<Shape, Set<Integer>>();
276-
private Map<Shape, Integer> occurrences = new HashMap<Shape, Integer>();
294+
private final Map<Shape, Set<Integer>> depths = new HashMap<>();
295+
private final Map<Shape, Integer> occurrences = new HashMap<>();
277296

278297
/**
279298
* Mark that a shape is observed at depth.

0 commit comments

Comments
 (0)