feat: add RequestParameters Support (#953)

Author: beck3905

examples/2016-10-31/function_request_parameters/src/index.js

@@ -0,0 +1,6 @@
+exports.handler = function(event, context, callback) {
+    callback(null, {
+        "statusCode": 200,
+        "body": "hello world" 
+    });
+}

examples/2016-10-31/function_request_parameters/template.yaml

@@ -0,0 +1,33 @@
+AWSTemplateFormatVersion: '2010-09-09'
+Transform: AWS::Serverless-2016-10-31
+Description: Simple API Endpoint configured using Swagger specified inline and backed by a Lambda function
+Globals:
+  Api:
+    CacheClusterEnabled: true
+    CacheClusterSize: '0.5'
+
+Resources:
+
+  MyLambdaFunction:
+    Type: AWS::Serverless::Function
+    Properties:
+      Handler: index.handler
+      Runtime: nodejs8.10
+      CodeUri: src/
+      Events:
+        GetApi:
+          Type: Api
+          Properties:
+            Path: /post
+            Method: POST
+            RequestParameters:
+              - method.request.header.Authorization:
+                  Required: true
+                  Caching: true
+              - method.request.querystring.type
+
+Outputs:
+
+  ApiURL:
+    Description: "API endpoint URL for Prod environment"
+    Value: !Sub "https://${ServerlessRestApi}.execute-api.${AWS::Region}.amazonaws.com/Prod/post"

samtranslator/model/eventsources/push.py

@@ -17,6 +17,8 @@
 
 CONDITION = 'Condition'
 
+REQUEST_PARAMETER_PROPERTIES = ["Required", "Caching"]
+
 
 class PushEventSource(ResourceMacro):
     """Base class for push event sources for SAM Functions.
@@ -397,7 +399,8 @@ class Api(PushEventSource):
             # Api Event sources must "always" be paired with a Serverless::Api
             'RestApiId': PropertyType(True, is_str()),
             'Auth': PropertyType(False, is_type(dict)),
-            'RequestModel': PropertyType(False, is_type(dict))
+            'RequestModel': PropertyType(False, is_type(dict)),
+            'RequestParameters': PropertyType(False, is_type(list))
     }
 
     def resources_to_link(self, resources):
@@ -607,6 +610,61 @@ def _add_swagger_integration(self, api, function):
                 editor.add_request_model_to_method(path=self.Path, method_name=self.Method,
                                                    request_model=self.RequestModel)
 
+        if self.RequestParameters:
+
+            default_value = {
+                'Required': False,
+                'Caching': False
+            }
+
+            parameters = []
+            for parameter in self.RequestParameters:
+
+                if isinstance(parameter, dict):
+
+                    parameter_name, parameter_value = next(iter(parameter.items()))
+
+                    if not re.match('method\.request\.(querystring|path|header)\.', parameter_name):
+                        raise InvalidEventException(
+                            self.relative_id,
+                            "Invalid value for 'RequestParameters' property. Keys must be in the format "
+                            "'method.request.[querystring|path|header].{value}', "
+                            "e.g 'method.request.header.Authorization'.")
+
+                    if not isinstance(parameter_value, dict) or not all(key in REQUEST_PARAMETER_PROPERTIES
+                                                                        for key in parameter_value.keys()):
+                        raise InvalidEventException(
+                            self.relative_id,
+                            "Invalid value for 'RequestParameters' property. Values must be an object, "
+                            "e.g { Required: true, Caching: false }")
+
+                    settings = default_value.copy()
+                    settings.update(parameter_value)
+                    settings.update({'Name': parameter_name})
+
+                    parameters.append(settings)
+
+                elif isinstance(parameter, string_types):
+                    if not re.match('method\.request\.(querystring|path|header)\.', parameter):
+                        raise InvalidEventException(
+                            self.relative_id,
+                            "Invalid value for 'RequestParameters' property. Keys must be in the format "
+                            "'method.request.[querystring|path|header].{value}', "
+                            "e.g 'method.request.header.Authorization'.")
+
+                    settings = default_value.copy()
+                    settings.update({'Name': parameter})
+
+                    parameters.append(settings)
+
+                else:
+                    raise InvalidEventException(
+                        self.relative_id,
+                        "Invalid value for 'RequestParameters' property. Property must be either a string or an object")
+
+            editor.add_request_parameters_to_method(path=self.Path, method_name=self.Method,
+                                                    request_parameters=parameters)
+
         api["DefinitionBody"] = editor.swagger
 
 

samtranslator/swagger/swagger.py

@@ -23,6 +23,7 @@ class SwaggerEditor(object):
     _X_APIGW_GATEWAY_RESPONSES = 'x-amazon-apigateway-gateway-responses'
     _X_APIGW_POLICY = 'x-amazon-apigateway-policy'
     _X_ANY_METHOD = 'x-amazon-apigateway-any-method'
+    _CACHE_KEY_PARAMETERS = 'cacheKeyParameters'
 
     def __init__(self, doc):
         """
@@ -820,6 +821,53 @@ def add_resource_policy(self, resource_policy):
 
             self._doc[self._X_APIGW_POLICY] = self.resource_policy
 
+    def add_request_parameters_to_method(self, path, method_name, request_parameters):
+        """
+        Add Parameters to Swagger.
+
+        :param string path: Path name
+        :param string method_name: Method name
+        :param list request_parameters: Dictionary of Parameters
+        :return:
+        """
+
+        normalized_method_name = self._normalize_method_name(method_name)
+        # It is possible that the method could have two definitions in a Fn::If block.
+        for method_definition in self.get_method_contents(self.get_path(path)[normalized_method_name]):
+
+            # If no integration given, then we don't need to process this definition (could be AWS::NoValue)
+            if not self.method_definition_has_integration(method_definition):
+                continue
+
+            existing_parameters = method_definition.get('parameters', [])
+
+            for request_parameter in request_parameters:
+
+                parameter_name = request_parameter['Name']
+                location_name = parameter_name.replace('method.request.', '')
+                location, name = location_name.split('.')
+
+                if location == 'querystring':
+                    location = 'query'
+
+                parameter = {
+                    'in': location,
+                    'name': name,
+                    'required': request_parameter['Required'],
+                    'type': 'string'
+                }
+
+                existing_parameters.append(parameter)
+
+                if request_parameter['Caching']:
+
+                    integration = method_definition[self._X_APIGW_INTEGRATION]
+                    cache_parameters = integration.get(self._CACHE_KEY_PARAMETERS, [])
+                    cache_parameters.append(parameter_name)
+                    integration[self._CACHE_KEY_PARAMETERS] = cache_parameters
+
+            method_definition['parameters'] = existing_parameters
+
     @property
     def swagger(self):
         """

tests/swagger/test_swagger.py

@@ -1116,6 +1116,7 @@ def test_must_add_body_parameter_to_method_openapi_required_true(self):
 
         self.assertEqual(expected, editor.swagger['paths']['/foo']['get']['requestBody'])
 
+
 class TestSwaggerEditor_add_auth(TestCase):
 
     def setUp(self):
@@ -1231,3 +1232,137 @@ def test_set_method_apikey_handling_apikeyrequired_true(self):
 
         self.editor._set_method_apikey_handling(path, method, True)
         self.assertEqual(expected, self.editor.swagger["paths"][path][method]["security"])
+
+
+class TestSwaggerEditor_add_request_parameter_to_method(TestCase):
+
+    def setUp(self):
+        self.original_swagger = {
+            "swagger": "2.0",
+            "paths": {
+                "/foo": {
+                    'get': {
+                        'x-amazon-apigateway-integration': {
+                            'test': 'must have integration'
+                        }
+                    }
+                }
+            }
+        }
+
+        self.editor = SwaggerEditor(self.original_swagger)
+
+    def test_must_add_parameter_to_method_with_required_and_caching_true(self):
+
+        parameters = [{
+            'Name': 'method.request.header.Authorization',
+            'Required': True,
+            'Caching': True
+        }]
+
+        self.editor.add_request_parameters_to_method('/foo', 'get', parameters)
+
+        expected_parameters = [
+            {
+                'in': 'header',
+                'required': True,
+                'name': 'Authorization',
+                'type': 'string'
+            }
+        ]
+
+        method_swagger = self.editor.swagger['paths']['/foo']['get']
+
+        self.assertEqual(expected_parameters, method_swagger['parameters'])
+        self.assertEqual(['method.request.header.Authorization'], method_swagger[_X_INTEGRATION]['cacheKeyParameters'])
+
+    def test_must_add_parameter_to_method_with_required_and_caching_false(self):
+
+        parameters = [{
+            'Name': 'method.request.header.Authorization',
+            'Required': False,
+            'Caching': False
+        }]
+
+        self.editor.add_request_parameters_to_method('/foo', 'get', parameters)
+
+        expected_parameters = [
+            {
+                'in': 'header',
+                'required': False,
+                'name': 'Authorization',
+                'type': 'string'
+            }
+        ]
+
+        method_swagger = self.editor.swagger['paths']['/foo']['get']
+
+        self.assertEqual(expected_parameters, method_swagger['parameters'])
+        self.assertNotIn('cacheKeyParameters', method_swagger[_X_INTEGRATION].keys())
+
+    def test_must_add_parameter_to_method_with_existing_parameters(self):
+
+        original_swagger = {
+            "swagger": "2.0",
+            "paths": {
+                "/foo": {
+                    'get': {
+                        'x-amazon-apigateway-integration': {
+                            'test': 'must have integration'
+                        },
+                        'parameters': [{'test': 'existing parameter'}]
+                    }
+                }
+            }
+        }
+
+        editor = SwaggerEditor(original_swagger)
+
+        parameters = [{
+            'Name': 'method.request.header.Authorization',
+            'Required': False,
+            'Caching': False
+        }]
+
+        editor.add_request_parameters_to_method('/foo', 'get', parameters)
+
+        expected_parameters = [
+            {
+                'test': 'existing parameter'
+            },
+            {
+                'in': 'header',
+                'required': False,
+                'name': 'Authorization',
+                'type': 'string'
+            }
+        ]
+
+        method_swagger = editor.swagger['paths']['/foo']['get']
+
+        self.assertEqual(expected_parameters, method_swagger['parameters'])
+        self.assertNotIn('cacheKeyParameters', method_swagger[_X_INTEGRATION].keys())
+
+    def test_must_not_add_parameter_to_method_without_integration(self):
+        original_swagger = {
+            "swagger": "2.0",
+            "paths": {
+                "/foo": {
+                    'get': {}
+                }
+            }
+        }
+
+        editor = SwaggerEditor(original_swagger)
+
+        parameters = [{
+            'Name': 'method.request.header.Authorization',
+            'Required': True,
+            'Caching': True
+        }]
+
+        editor.add_request_parameters_to_method('/foo', 'get', parameters)
+
+        expected = {}
+
+        self.assertEqual(expected, editor.swagger['paths']['/foo']['get'])