docs: add resource policy to spec docs (#1103)

Author: praneetap

versions/2016-10-31.md

@@ -227,7 +227,7 @@ EndpointConfiguration | `string` | Specify the type of endpoint for API endpoint
 BinaryMediaTypes | List of `string` |  List of MIME types that your API could return. Use this to enable binary support for APIs. Use `~1` instead of `/` in the mime types (See examples in [template.yaml](../examples/2016-10-31/implicit_api_settings/template.yaml)).
 MinimumCompressionSize | `int` | Allow compression of response bodies based on client's Accept-Encoding header. Compression is triggered when response body size is greater than or equal to your configured threshold. The maximum body size threshold is 10 MB (10,485,760 Bytes). The following compression types are supported: gzip, deflate, and identity.
 Cors | `string` or [Cors Configuration](#cors-configuration) | Enable CORS for all your APIs. Specify the domain to allow as a string or specify a dictionary with additional [Cors Configuration](#cors-configuration). NOTE: Cors requires SAM to modify your Swagger definition. Hence it works only inline swagger defined with `DefinitionBody`.
-Auth | [API Auth Object](#api-auth-object) | Auth configuration for this API. Define Lambda and Cognito `Authorizers` and specify a `DefaultAuthorizer` for this API. Can specify default ApiKey restriction using `ApiKeyRequired`.
+Auth | [API Auth Object](#api-auth-object) | Auth configuration for this API. Define Lambda and Cognito `Authorizers` and specify a `DefaultAuthorizer` for this API. Can specify default ApiKey restriction using `ApiKeyRequired`. Also define `ResourcePolicy` and specify `CustomStatements` which is a list of policy statements that will be added to the resource policies on the API.
 GatewayResponses | Map of [Gateway Response Type](https://docs.aws.amazon.com/apigateway/api-reference/resource/gateway-response/) to [Gateway Response Object](#gateway-response-object) | Configures Gateway Reponses for an API. Gateway Responses are responses returned by API Gateway, either directly or through the use of Lambda Authorizers. Keys for this object are passed through to Api Gateway, so any value supported by `GatewayResponse.responseType` is supported here.
 AccessLogSetting | [CloudFormation AccessLogSetting property](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-properties-apigateway-stage-accesslogsetting.html) | Configures Access Log Setting for a stage. This value is passed through to CloudFormation, so any value supported by `AccessLogSetting` is supported here.
 CanarySetting | [CloudFormation CanarySetting property](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-properties-apigateway-stage-canarysetting.html) | Configure a Canary Setting to a Stage of a regular deployment. This value is passed through to Cloudformation, so any value supported by `CanarySetting` is supported here.
@@ -530,7 +530,7 @@ Property Name | Type | Description
 Path | `string` | **Required.** Uri path for which this function is invoked. MUST start with `/`.
 Method | `string` | **Required.** HTTP method for which this function is invoked.
 RestApiId | `string` | Identifier of a RestApi resource which MUST contain an operation with the given path and method. Typically, this is set to [reference](http://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/intrinsic-function-reference-ref.html) an `AWS::Serverless::Api` resource defined in this template. If not defined, a default `AWS::Serverless::Api` resource is created using a generated Swagger document contains a union of all paths and methods defined by `Api` events defined in this template that do not specify a RestApiId.
-Auth | [Function Auth Object](#function-auth-object) | Auth configuration for this specific Api+Path+Method. Useful for overriding the API's `DefaultAuthorizer` setting auth config on an individual path when no `DefaultAuthorizer` is specified or overriding the default `ApiKeyRequired' setting.
+Auth | [Function Auth Object](#function-auth-object) | Auth configuration for this specific Api+Path+Method. Useful for overriding the API's `DefaultAuthorizer` setting auth config on an individual path when no `DefaultAuthorizer` is specified or overriding the default `ApiKeyRequired` setting.
 RequestModel | [Function Request Model Object](#function-request-model-object) | Request model configuration for this specific Api+Path+Method.
 RequestParameters | List of `string` <span>&#124;</span> List of [Function Request Parameter Object](#function-request-parameter-object) | Request parameters configuration for this specific Api+Path+Method. All parameter names must start with `method.request` and must be limited to `method.request.header`, `method.request.querystring`, or `method.request.path`. If a parameter is a `string` and NOT a [Function Request Parameter Object](#function-request-parameter-object) then `Required` and `Caching` will default to `False`.
 
@@ -825,6 +825,14 @@ Auth:
   ApiKeyRequired: true # OPTIONAL
   DefaultAuthorizer: MyCognitoAuth # OPTIONAL, if you use IAM permissions, specify AWS_IAM.
   AddDefaultAuthorizerToCorsPreflight: false # OPTIONAL; Default: true
+  ResourcePolicy:
+    CustomStatements: 
+      - Effect: Allow
+        Principal: *
+        Action: execute-api:Invoke
+        ...
+```
+
   # For AWS_IAM:
   # DefaultAuthorizer: AWS_IAM
   # InvokeRole: NONE # CALLER_CREDENTIALS by default unless overridden
@@ -869,6 +877,18 @@ Auth:
   ApiKeyRequired: true
 ```
 
+**ResourcePolicy:**
+Configure Resource Policy for all methods and paths on an API. This setting can also be defined on individual `AWS::Serverless::Function` using the [Function Auth Object](#function-auth-object). This is required for APIs with `EndpointConfiguration: PRIVATE`.
+
+```yaml
+Auth:
+  ResourcePolicy:
+    CustomStatements: 
+      - Effect: Allow
+        Principal: *
+        Action: execute-api:Invoke
+        ...
+```
 
 #### Function Auth Object