Give context to OpenAPI value transformer

This updates AbstractRestProtocol's value transformer to take
the conversion context and the shape of the value it is transforming.

Author: JordonPhillips

smithy-openapi/src/main/java/software/amazon/smithy/openapi/fromsmithy/protocols/AbstractRestProtocol.java

@@ -109,11 +109,16 @@ abstract Schema createDocumentSchema(
             MessageType messageType
     );
 
+    @Deprecated
+    Node transformSmithyValueToProtocolValue(Node value) {
+        return value;
+    };
+
     /**
      * Converts Smithy values in Node form to a data exchange format used by a protocol (e.g., XML).
      * Then returns the converted value as a long string (escaping where necessary).
      * If data exchange format is JSON (e.g., as in restJson1 protocol),
-     * method should return values without any modification.
+     * method should respect the jsonName trait, but otherwise not modify the node.
      *
      * <p> Used for the value property of OpenAPI example objects.
      * For protocols that do not use JSON as data-exchange format,
@@ -122,10 +127,14 @@ abstract Schema createDocumentSchema(
      * E.g., for restXML protocol, values would be converted to a large String of XML value / object,
      * escaping where necessary.
      *
-     * @param value    value to be converted.
+     * @param context Conversion context.
+     * @param shape The shape that the value represents.
+     * @param value value to be converted.
      * @return  the long string (escaped where necessary) of values in a data exchange format used by a protocol.
      */
-    abstract Node transformSmithyValueToProtocolValue(Node value);
+    Node transformSmithyValueToProtocolValue(Context<T> context, Shape shape, Node value) {
+        return value;
+    }
 
     @Override
     public Set<String> getProtocolRequestHeaders(Context<T> context, OperationShape operationShape) {
@@ -204,6 +213,7 @@ private List<ParameterObject> createPathParameters(Context<T> context, Operation
                     .in("path")
                     .schema(schema)
                     .examples(createExamplesForMembersWithHttpTraits(
+                            context,
                             operation,
                             binding,
                             MessageType.REQUEST,
@@ -219,6 +229,7 @@ private List<ParameterObject> createPathParameters(Context<T> context, Operation
      * path parameters, query parameters, header parameters, and payload.
      */
     private Map<String, Node> createExamplesForMembersWithHttpTraits(
+            Context<T> context,
             Shape operationOrError,
             HttpBinding binding,
             MessageType type,
@@ -229,15 +240,17 @@ private Map<String, Node> createExamplesForMembersWithHttpTraits(
         }
 
         if (type == MessageType.ERROR) {
-            return createErrorExamplesForMembersWithHttpTraits(operationOrError, binding, operation);
+            return createErrorExamplesForMembersWithHttpTraits(context, operationOrError, binding, operation);
         } else {
             Map<String, Node> examples = new TreeMap<>();
             // unique numbering for unique example names in OpenAPI.
             int uniqueNum = 1;
 
-            Optional<ExamplesTrait> examplesTrait = operationOrError.getTrait(ExamplesTrait.class);
-            for (ExamplesTrait.Example example : examplesTrait.map(ExamplesTrait::getExamples)
-                    .orElse(Collections.emptyList())) {
+            List<ExamplesTrait.Example> modeledExamples = operationOrError.getTrait(ExamplesTrait.class)
+                    .map(ExamplesTrait::getExamples)
+                    .orElse(Collections.emptyList());
+
+            for (ExamplesTrait.Example example : modeledExamples) {
                 ObjectNode inputOrOutput = type == MessageType.REQUEST ? example.getInput()
                         : example.getOutput().orElse(Node.objectNode());
                 String name = operationOrError.getId().getName() + "_example" + uniqueNum++;
@@ -251,7 +264,7 @@ private Map<String, Node> createExamplesForMembersWithHttpTraits(
                             ExampleObject.builder()
                                     .summary(example.getTitle())
                                     .description(example.getDocumentation().orElse(""))
-                                    .value(transformSmithyValueToProtocolValue(values))
+                                    .value(transformSmithyValueToProtocolValue(context, binding.getMember(), values))
                                     .build()
                                     .toNode());
                 }
@@ -264,6 +277,7 @@ private Map<String, Node> createExamplesForMembersWithHttpTraits(
      * Helper method for createExamples() method.
      */
     private Map<String, Node> createErrorExamplesForMembersWithHttpTraits(
+            Context<T> context,
             Shape error,
             HttpBinding binding,
             OperationShape operation
@@ -290,7 +304,7 @@ private Map<String, Node> createErrorExamplesForMembersWithHttpTraits(
                         ExampleObject.builder()
                                 .summary(example.getTitle())
                                 .description(example.getDocumentation().orElse(""))
-                                .value(transformSmithyValueToProtocolValue(values))
+                                .value(transformSmithyValueToProtocolValue(context, binding.getMember(), values))
                                 .build()
                                 .toNode());
             }
@@ -302,6 +316,7 @@ private Map<String, Node> createErrorExamplesForMembersWithHttpTraits(
      * This method is used for converting the Smithy examples to OpenAPI examples for non-payload HTTP message body.
      */
     private Map<String, Node> createBodyExamples(
+            Context<T> context,
             Shape operationOrError,
             List<HttpBinding> bindings,
             MessageType type,
@@ -312,7 +327,7 @@ private Map<String, Node> createBodyExamples(
         }
 
         if (type == MessageType.ERROR) {
-            return createErrorBodyExamples(operationOrError, bindings, operation);
+            return createErrorBodyExamples(context, operationOrError, bindings, operation);
         } else {
             Map<String, Node> examples = new TreeMap<>();
             // unique numbering for unique example names in OpenAPI.
@@ -321,18 +336,30 @@ private Map<String, Node> createBodyExamples(
             Optional<ExamplesTrait> examplesTrait = operationOrError.getTrait(ExamplesTrait.class);
             for (ExamplesTrait.Example example : examplesTrait.map(ExamplesTrait::getExamples)
                     .orElse(Collections.emptyList())) {
+
+                Shape structure = operationOrError;
+                if (operationOrError.isOperationShape()) {
+                    OperationShape op = operationOrError.asOperationShape().get();
+                    if (type == MessageType.REQUEST) {
+                        structure = context.getModel().expectShape(op.getInputShape());
+                    } else {
+                        structure = context.getModel().expectShape(op.getOutputShape());
+                    }
+                }
+
                 // get members included in bindings
                 ObjectNode values = getMembersWithHttpBindingTrait(bindings,
                         type == MessageType.REQUEST ? example.getInput()
                                 : example.getOutput().orElse(Node.objectNode()));
                 String name = operationOrError.getId().getName() + "_example" + uniqueNum++;
+
                 // this if condition is needed to avoid errors when converting examples of response.
                 if (!example.getError().isPresent() || type == MessageType.REQUEST) {
                     examples.put(name,
                             ExampleObject.builder()
                                     .summary(example.getTitle())
                                     .description(example.getDocumentation().orElse(""))
-                                    .value(transformSmithyValueToProtocolValue(values))
+                                    .value(transformSmithyValueToProtocolValue(context, structure, values))
                                     .build()
                                     .toNode());
                 }
@@ -342,6 +369,7 @@ private Map<String, Node> createBodyExamples(
     }
 
     private Map<String, Node> createErrorBodyExamples(
+            Context<T> context,
             Shape error,
             List<HttpBinding> bindings,
             OperationShape operation
@@ -362,7 +390,7 @@ private Map<String, Node> createErrorBodyExamples(
                         ExampleObject.builder()
                                 .summary(example.getTitle())
                                 .description(example.getDocumentation().orElse(""))
-                                .value(transformSmithyValueToProtocolValue(values))
+                                .value(transformSmithyValueToProtocolValue(context, error, values))
                                 .build()
                                 .toNode());
             }
@@ -456,7 +484,8 @@ private List<ParameterObject> createQueryParameters(Context<T> context, Operatio
             }
 
             param.schema(createQuerySchema(context, member, target));
-            param.examples(createExamplesForMembersWithHttpTraits(operation, binding, MessageType.REQUEST, null));
+            param.examples(
+                    createExamplesForMembersWithHttpTraits(context, operation, binding, MessageType.REQUEST, null));
             result.add(param.build());
         }
 
@@ -496,7 +525,8 @@ private Map<String, ParameterObject> createHeaderParameters(
                 param.in(null).name(null);
             }
 
-            param.examples(createExamplesForMembersWithHttpTraits(operationOrError, binding, messageType, operation));
+            param.examples(
+                    createExamplesForMembersWithHttpTraits(context, operationOrError, binding, messageType, operation));
 
             // Create the appropriate schema based on the shape type.
             Shape target = context.getModel().expectShape(member.getTarget());
@@ -566,6 +596,7 @@ private Optional<RequestBodyObject> createRequestPayload(
             return shapeName + "InputPayload";
         }).toBuilder()
                 .examples(createExamplesForMembersWithHttpTraits(
+                        context,
                         operation,
                         binding,
                         MessageType.REQUEST,
@@ -598,7 +629,7 @@ private Optional<RequestBodyObject> createRequestDocument(
         String pointer = context.putSynthesizedSchema(synthesizedName, schema);
         MediaTypeObject mediaTypeObject = MediaTypeObject.builder()
                 .schema(Schema.builder().ref(pointer).build())
-                .examples(createBodyExamples(operation, bindings, MessageType.REQUEST, null))
+                .examples(createBodyExamples(context, operation, bindings, MessageType.REQUEST, null))
                 .build();
 
         // If any of the top level bindings are required, then the body itself must be required.
@@ -757,6 +788,7 @@ private void createResponsePayload(
                     : shapeName + "ErrorPayload";
         }).toBuilder()
                 .examples(createExamplesForMembersWithHttpTraits(
+                        context,
                         operationOrError,
                         binding,
                         type,
@@ -840,7 +872,7 @@ private void createResponseDocumentIfNeeded(
         String pointer = context.putSynthesizedSchema(synthesizedName, schema);
         MediaTypeObject mediaTypeObject = MediaTypeObject.builder()
                 .schema(Schema.builder().ref(pointer).build())
-                .examples(createBodyExamples(operationOrError, bindings, messageType, operation))
+                .examples(createBodyExamples(context, operationOrError, bindings, messageType, operation))
                 .build();
 
         responseBuilder.putContent(mediaType, mediaTypeObject);

smithy-openapi/src/main/java/software/amazon/smithy/openapi/fromsmithy/protocols/AwsRestJson1Protocol.java

@@ -166,7 +166,7 @@ private boolean hasSingleUnionMember(StructureShape shape, Model model) {
     }
 
     @Override
-    Node transformSmithyValueToProtocolValue(Node value) {
+    Node transformSmithyValueToProtocolValue(Context<RestJson1Trait> context, Shape shape, Node value) {
         return value;
     }
 }