Repository: serverless/serverless (JavaScript)
Task: Feature (2018-11-20 14:59:20+00:00)

Issue:
Support API Gateway stage deployment description
# This is a Feature Proposal

## Description

Currently, [API Gateway deployment](https://github.com/serverless/serverless/blob/master/lib/plugins/aws/package/compile/events/apiGateway/lib/deployment.js#L14) only support **RestApiId** and **StageName** property.

In [AWS::ApiGateway::Deployment](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-resource-apigateway-deployment.html#cfn-apigateway-deployment-description) doc, it supports follow Properties:

```
{
  "Type" : "AWS::ApiGateway::Deployment",
  "Properties" : {
    "DeploymentCanarySettings" : DeploymentCanarySettings,
    "Description" : String,
    "RestApiId" : String,
    "StageDescription" : StageDescription,
    "StageName" : String
  }
}
```

For feature proposals:
* What is the use case that should be solved 
   Support **Description** property so that the deployment history can have descriptions as well.
* If there is additional config how would it look
   In serverless.yml 

```
    stage:
        name: dev
        description:  my stage deployment description 
```



Similar or dependent issues:
* None

## Additional Data

* ***Serverless Framework Version you're using***: 1.32.0
* ***Operating System***: Linux
* ***Stack Trace***:
* ***Provider Error messages***:



Discussion:

Patch:
diff --git a/docs/providers/aws/events/apigateway.md b/docs/providers/aws/events/apigateway.md
index 3449c6a836c..62f2f50e0ea 100644
--- a/docs/providers/aws/events/apigateway.md
+++ b/docs/providers/aws/events/apigateway.md
@@ -981,6 +981,7 @@ provider:
   apiGateway:
     restApiId: xxxxxxxxxx # REST API resource ID. Default is generated by the framework
     restApiRootResourceId: xxxxxxxxxx # Root resource, represent as / path
+    description: Some Description # optional - description of deployment history
 
 functions:
   ...
@@ -996,6 +997,7 @@ provider:
   apiGateway:
     restApiId: xxxxxxxxxx
     restApiRootResourceId: xxxxxxxxxx
+    description: Some Description
 
 functions:
   create:
@@ -1012,6 +1014,7 @@ provider:
   apiGateway:
     restApiId: xxxxxxxxxx
     restApiRootResourceId: xxxxxxxxxx
+    description: Some Description
 
 functions:
   create:
@@ -1030,6 +1033,7 @@ provider:
   apiGateway:
     restApiId: xxxxxxxxxx
     restApiRootResourceId: xxxxxxxxxx
+    description: Some Description
     restApiResources:
       /posts: xxxxxxxxxx
 
@@ -1044,6 +1048,7 @@ provider:
   apiGateway:
     restApiId: xxxxxxxxxx
     restApiRootResourceId: xxxxxxxxxx
+    description: Some Description
     restApiResources:
       /posts: xxxxxxxxxx
 
@@ -1061,6 +1066,7 @@ provider:
   apiGateway:
     restApiId: xxxxxxxxxx
     # restApiRootResourceId: xxxxxxxxxx # Optional
+    description: Some Description
     restApiResources:
       /posts: xxxxxxxxxx
       /categories: xxxxxxxxx
diff --git a/docs/providers/aws/guide/serverless.yml.md b/docs/providers/aws/guide/serverless.yml.md
index a735bfb5e6c..6fc7f54bcee 100644
--- a/docs/providers/aws/guide/serverless.yml.md
+++ b/docs/providers/aws/guide/serverless.yml.md
@@ -61,6 +61,7 @@ provider:
       '/users/create': xxxxxxxxxx
     apiKeySourceType: HEADER # Source of API key for usage plan. HEADER or AUTHORIZER.
     minimumCompressionSize: 1024 # Compress response when larger than specified size in bytes (must be between 0 and 10485760)
+    description: Some Description # optional description for the API Gateway stage deployment
   usagePlan: # Optional usage plan configuration
     quota:
       limit: 5000
diff --git a/lib/plugins/aws/package/compile/events/apiGateway/lib/deployment.js b/lib/plugins/aws/package/compile/events/apiGateway/lib/deployment.js
index 9eb923ba596..57e16cc053b 100644
--- a/lib/plugins/aws/package/compile/events/apiGateway/lib/deployment.js
+++ b/lib/plugins/aws/package/compile/events/apiGateway/lib/deployment.js
@@ -14,6 +14,7 @@ module.exports = {
         Properties: {
           RestApiId: this.provider.getApiGatewayRestApiId(),
           StageName: this.provider.getStage(),
+          Description: this.provider.getApiGatewayDescription(),
         },
         DependsOn: this.apiGatewayMethodLogicalIds,
       },
diff --git a/lib/plugins/aws/provider/awsProvider.js b/lib/plugins/aws/provider/awsProvider.js
index fec6d92e31b..6b71d0831f1 100644
--- a/lib/plugins/aws/provider/awsProvider.js
+++ b/lib/plugins/aws/provider/awsProvider.js
@@ -485,6 +485,14 @@ class AwsProvider {
     return { Ref: this.naming.getRestApiLogicalId() };
   }
 
+  getApiGatewayDescription() {
+    if (this.serverless.service.provider.apiGateway
+      && this.serverless.service.provider.apiGateway.description) {
+      return this.serverless.service.provider.apiGateway.description;
+    }
+    return undefined;
+  }
+
   getMethodArn(accountId, apiId, method, pathParam) {
     const region = this.getRegion();
     let path = pathParam;


Test patch:
diff --git a/lib/plugins/aws/package/compile/events/apiGateway/lib/deployment.test.js b/lib/plugins/aws/package/compile/events/apiGateway/lib/deployment.test.js
index 98be9ee278e..a3354e05d09 100644
--- a/lib/plugins/aws/package/compile/events/apiGateway/lib/deployment.test.js
+++ b/lib/plugins/aws/package/compile/events/apiGateway/lib/deployment.test.js
@@ -44,12 +44,42 @@ describe('#compileDeployment()', () => {
           RestApiId: {
             Ref: awsCompileApigEvents.apiGatewayRestApiLogicalId,
           },
+          Description: undefined,
           StageName: 'dev',
         },
       });
     })
   );
 
+  it('should create a deployment resource with description', () => {
+    awsCompileApigEvents.serverless.service.provider.apiGateway = {
+      description: 'Some Description',
+    };
+
+    return awsCompileApigEvents
+      .compileDeployment().then(() => {
+        const apiGatewayDeploymentLogicalId = Object
+          .keys(awsCompileApigEvents.serverless.service.provider
+              .compiledCloudFormationTemplate.Resources)[0];
+
+        expect(
+            awsCompileApigEvents.serverless.service.provider.compiledCloudFormationTemplate
+              .Resources[apiGatewayDeploymentLogicalId]
+          ).to.deep.equal({
+            Type: 'AWS::ApiGateway::Deployment',
+            DependsOn: ['method-dependency1', 'method-dependency2'],
+            Properties: {
+              RestApiId: {
+                Ref: awsCompileApigEvents.apiGatewayRestApiLogicalId,
+              },
+              Description: 'Some Description',
+              StageName: 'dev',
+            },
+          });
+      });
+  }
+  );
+
   it('should add service endpoint output', () =>
     awsCompileApigEvents.compileDeployment().then(() => {
       expect(