Specification changes and examples for new features

1. Inline Swagger
2. CodeUri & DefinitionUri support Body, Key and Version dictionary
3. FunctionName property

Author: sanathkr

HOWTO.md

@@ -81,3 +81,71 @@ aws cloudformation deploy \
 ```
 
 Refer to the [documentation](http://docs.aws.amazon.com/cli/latest/reference/cloudformation/deploy/index.html) for more details.
+
+## Using Intrinsic Functions
+CloudFormation provides handy functions you can use to generate values at runtime. These are called [Intrinsic Functions](http://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/intrinsic-function-reference.html). Since SAM is deployed using CloudFormation, you can use these intrinsic functions within SAM as well. Here are some examples:
+
+#### Dynamically set S3 location of Lambda function code zip
+```
+Transform: 'AWS::Serverless-2016-10-31'
+
+# Parameters are CloudFormation features to pass input
+# to your template when you create a stack
+Parameters:
+    BucketName:
+        Type: String
+    CodeKey:
+        Type: String
+
+Resources:
+    MyFunction:
+        Type: AWS::Serverless::Function
+        Properties:
+            Handler: index.handler
+            Runtime: nodejs4.3
+            CodeUri:
+                # !Ref function allows you to fetch value 
+                # of parameters and other resources at runtime
+                Bucket: !Ref BucketName
+                Key: !Ref CodeKey
+```
+
+#### Generate a different function name for each stack
+
+```
+Transform: 'AWS::Serverless-2016-10-31'
+
+# Parameters are CloudFormation features to pass input
+# to your template when you create a stack
+Parameters:
+    FunctionNameSuffix:
+        Type: String
+    
+Resources:
+    MyFunction:
+        Type: AWS::Serverless::Function
+        Properties:
+
+            # !Sub performs string substitution
+            FunctionName: !Sub "mylambda-${FunctionNameSuffix}"
+
+            Handler: index.handler
+            Runtime: nodejs4.3
+            CodeUri: s3://bucket/key
+```
+
+### Caveats:
+#### ImportValue is partially supported
+[`ImportValue`](http://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/intrinsic-function-reference-importvalue.html) allows one stack to refer to value of properties from another stack. ImportValue is supported on most properties, except the very few that SAM needs to parse. Following properties are *not* supported:
+
+- `RestApiId` of `AWS::Serverless::Function`
+- `Policies` of `AWS::Serverless::Function`
+- `StageName` of `AWS::Serverless::Api`
+
+
+
+
+
+
+
+

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

@@ -1,10 +1,17 @@
 AWSTemplateFormatVersion : '2010-09-09'
 Transform: AWS::Serverless-2016-10-31
 Description: A hello world application.
+Parameters:
+    Bucket:
+        Type: String
+    CodeZipKey:
+        Type: String
 Resources:
   HelloWorldFunction:
     Type: AWS::Serverless::Function
     Properties:
       Handler: index.handler
       Runtime: nodejs4.3
-      CodeUri: s3://<bucket>/hello_world.zip
+      CodeUri: 
+        Bucket: !Bucket
+        Key: !CodeZipKey

examples/2016-10-31/inline_swagger/index.js

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

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

@@ -0,0 +1,41 @@
+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
+Resources:
+  MyApi:
+    Type: AWS::Serverless::Api
+    Properties:
+        StageName: prod
+        DefinitionBody:
+            swagger: 2.0
+            info:
+              title:
+                Ref: AWS::StackName
+            paths:
+              "/get":
+                get:
+                  x-amazon-apigateway-integration:
+                    httpMethod: POST
+                    type: aws_proxy
+                    uri:
+                      Fn::Sub: arn:aws:apigateway:${AWS::Region}:lambda:path/2015-03-31/functions/${MyLambdaFunction.Arn}/invocations
+                  responses: {}
+            swagger: '2.0'
+
+
+            
+  MyLambdaFunction:
+    Type: AWS::Serverless::Function
+    Properties:
+      Handler: index.handler
+      Runtime: nodejs4.3
+      CodeUri: s3://<bucket>/inline_swagger.zip
+      Events:
+        GetApi:
+          Type: Api
+          Properties:
+            Path: /get
+            Method: GET
+            RestApiId: 
+                Ref: MyApi
+

versions/2016-10-31.md

@@ -62,7 +62,8 @@ Property Name | Type | Description
 ---|:---:|---
 Handler | `string` | **Required.** Function within your code that is called to begin execution.
 Runtime | `string` | **Required.** The runtime environment.
-CodeUri | `string` | **Required.** S3 Uri to the function code. The S3 object this Uri references MUST be a [Lambda deployment package](http://docs.aws.amazon.com/lambda/latest/dg/deployment-package-v2.html).
+CodeUri | `string` <span>&#124;</span> [S3 Location Object](#s3-location-object) | **Required.** S3 Uri or location to the function code. The S3 object this Uri references MUST be a [Lambda deployment package](http://docs.aws.amazon.com/lambda/latest/dg/deployment-package-v2.html).
+FunctionName | `string` | A name for the function. If you don't specify a name, a unique name will be generated for you. [More Info](http://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-resource-lambda-function.html#cfn-lambda-function-functionname)
 Description | `string` | Description of the function.
 MemorySize | `integer` | Size of the memory allocated per invocation of the function in MB. Defaults to 128.
 Timeout | `integer` | Maximum time that the function can run before it is killed in seconds. Defaults to 3.
@@ -117,7 +118,8 @@ An `AWS::Serverless::Api` resource need not be explicitly added to a AWS Serverl
 Property Name | Type | Description
 ---|:---:|---
 StageName | `string` | **Required** The name of the stage, which API Gateway uses as the first path segment in the invoke Uniform Resource Identifier (URI).
-DefinitionUri | `string` | **Required** S3 URI to the Swagger document describing the API.
+DefinitionUri | `string` <span>&#124;</span> [S3 Location Object](#s3-location-object) | S3 URI or location to the Swagger document describing the API. Either one of `DefinitionUri` or `DefinitionBody` must be specified.
+DefinitionBody | `JSON or YAML Object` | Swagger specification that describes your API. Either one of `DefinitionUri` or `DefinitionBody` must be specified.
 CacheClusterEnabled | `boolean` | Indicates whether cache clustering is enabled for the stage.
 CacheClusterSize | `string` | The stage's cache cluster size.
 Variables | Map of `string` to `string` | A map (string to string map) that defines the stage variables, where the variable name is the key and the variable value is the value. Variable names are limited to alphanumeric characters. Values must match the following regular expression: `[A-Za-z0-9._~:/?#&amp;=,-]+`.
@@ -396,3 +398,15 @@ Type | `string` | Attribute type of the primary key. MUST be one of `String`, `N
 Name: id
 Type: String
 ```
+
+### Data Types
+#### S3 Location Object
+Specifies the location of an S3 object as a dictionary containing `Bucket`, `Key`, and optional `Version` properties.
+
+Example:
+```
+CodeUri:
+  Bucket: mybucket-name
+  Key: code.zip
+  Version: 121212
+```