Download documentation from AWS Api Gateway (#80)

* Feature: download documentation

Author: aaleksandrov

README.md

@@ -298,6 +298,11 @@ ApiGatewayMethod{normalizedPath}{normalizedMethod}:
 
 See the Serverless documentation for more information on [resource naming](https://serverless.com/framework/docs/providers/aws/guide/resources/), and the AWS documentation for more information on [request parameters](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-properties-apitgateway-method-integration.html#cfn-apigateway-method-integration-requestparameters).
 
+### Download documentation from AWS API Gateway
+
+To download the deployed documentation you just need to use `serverless downloadDocumentation --outputFile=filename.ext`.
+For `yml` or `yaml` extensions application/yaml content will be downloaded from AWS. In any other case - application/json. 
+
 ## Contribution
 
 When you think something is missing or found some bug, please add an issue to this repo. If you want

package.json

@@ -5,7 +5,7 @@
   "main": "src/index.js",
   "scripts": {
     "codecov": "cat coverage/*/lcov.info | codecov",
-    "test": "istanbul cover -x \"src/index.spec.js\" jasmine ./src/index.spec.js ./src/documentation.spec.js ./src/models.spec.js",
+    "test": "istanbul cover -x \"src/index.spec.js\" jasmine ./src/index.spec.js ./src/documentation.spec.js ./src/models.spec.js ./src/downloadDocumentation.spec.js",
     "test:nocoverage": "jasmine ./src/index.spec.js"
   },
   "repository": "9cookies/serverless-aws-documentation",

src/downloadDocumentation.js

@@ -0,0 +1,47 @@
+'use strict';
+
+module.exports = {
+  downloadDocumentation: function () {
+    const aws = this.serverless.providers.aws;
+    const stackName = aws.naming.getStackName(this.serverless.service.provider.stage);
+    return this._getRestApiId(stackName).then((restApiId) => {
+      return aws.request('APIGateway', 'getExport', {
+        stageName: this.serverless.service.provider.stage,
+        restApiId: restApiId,
+        exportType: 'swagger',
+        accepts: createAWSContentType(this.options.outputFileName),
+      });
+    }).then((response) => {
+      this.fs.writeFileSync(this.options.outputFileName, response.body);
+    });
+  },
+
+  _getRestApiId: function (stackName) {
+    return this.serverless.providers.aws.request('CloudFormation', 'describeStacks', {StackName: stackName},
+      this.serverless.service.provider.stage,
+      this.serverless.service.provider.region
+    ).then((result) => {
+      return result.Stacks[0].Outputs
+        .filter(output => output.OutputKey === 'AwsDocApiId')
+        .map(output => output.OutputValue)[0];
+    });
+  },
+};
+
+function getFileExtension(filename) {
+  const path = require('path');
+  let ext = path.extname(filename || '').split('.');
+
+  return ext[ext.length - 1];
+}
+
+function createAWSContentType(outputFileName) {
+  const fileExtension = getFileExtension(outputFileName);
+  let awsContentType = 'application/json';
+  if (fileExtension === 'yml' || fileExtension === 'yaml') {
+    awsContentType = 'application/yaml';
+  }
+
+  return awsContentType;
+}
+

src/downloadDocumentation.spec.js

@@ -0,0 +1,123 @@
+describe('ServerlessAWSDocumentation', function () {
+  let objectUnderTest;
+
+  beforeEach(() => {
+    objectUnderTest = require('./downloadDocumentation.js');
+    objectUnderTest.fs = {
+      writeFileSync: jasmine.createSpy('fs')
+    };
+    objectUnderTest.serverless = {
+      providers: {
+        aws: {
+          naming: {
+            getStackName: () => {
+              return 'testStackName';
+            }
+          },
+          request: jasmine.createSpy('aws request'),
+        }
+      },
+      service: {
+        provider: {
+          stage: 'testStage',
+          region: 'testRegion',
+        }
+      }
+    };
+  });
+
+  afterEach(() => {
+    delete require.cache[require.resolve('./downloadDocumentation.js')];
+  });
+
+  describe('downloadDocumentation', () => {
+    it('should successfully download documentation, unknown file extension', (done) => {
+      objectUnderTest.options = {
+        outputFileName: 'test.txt',
+      };
+      objectUnderTest._getRestApiId = () => {
+        return Promise.resolve('testRestApiId')
+      };
+
+      objectUnderTest.serverless.providers.aws.request.and.returnValue(Promise.resolve({
+        body: 'some body',
+      }));
+      return objectUnderTest.downloadDocumentation().then(() => {
+        expect(objectUnderTest.serverless.providers.aws.request).toHaveBeenCalledWith('APIGateway', 'getExport', {
+          stageName: 'testStage',
+          restApiId: 'testRestApiId',
+          exportType: 'swagger',
+          accepts: 'application/json',
+        });
+        expect(objectUnderTest.fs.writeFileSync).toHaveBeenCalledWith('test.txt', 'some body');
+
+        done();
+      });
+    });
+
+    it('should successfully download documentation, yaml extension', (done) => {
+      objectUnderTest.options = {
+        outputFileName: 'test.yml',
+      };
+      objectUnderTest._getRestApiId = () => {
+        return Promise.resolve('testRestApiId')
+      };
+
+      objectUnderTest.serverless.providers.aws.request.and.returnValue(Promise.resolve({
+        body: 'some body',
+      }));
+      return objectUnderTest.downloadDocumentation().then(() => {
+        expect(objectUnderTest.serverless.providers.aws.request).toHaveBeenCalledWith('APIGateway', 'getExport', {
+          stageName: 'testStage',
+          restApiId: 'testRestApiId',
+          exportType: 'swagger',
+          accepts: 'application/yaml',
+        });
+        expect(objectUnderTest.fs.writeFileSync).toHaveBeenCalledWith('test.yml', 'some body');
+
+        done();
+      });
+    });
+
+    it('should throw an error', (done) => {
+      objectUnderTest.options = {
+        outputFileName: 'test.json',
+      };
+      objectUnderTest._getRestApiId = () => {
+        return Promise.resolve('testRestApiId');
+      };
+      objectUnderTest.serverless.providers.aws.request.and.returnValue(Promise.reject('reason'));
+      return objectUnderTest.downloadDocumentation().catch(() => {
+        done();
+      });
+    });
+
+    it('should get rest api id', (done) => {
+      objectUnderTest.serverless.providers.aws.request.and.returnValue(Promise.resolve({
+        Stacks: [{
+          Outputs: [{
+            OutputKey: 'some-key-1',
+            OutputValue: 'some-value-1',
+          }, {
+            OutputKey: 'AwsDocApiId',
+            OutputValue: 'testRestApiId',
+          }, {
+            OutputKey: 'some-key-2',
+            OutputValue: 'some-value-2',
+          }]
+        }]
+      }));
+
+      return objectUnderTest._getRestApiId('testStackName').then((restApiId) => {
+        expect(restApiId).toBe('testRestApiId');
+        expect(objectUnderTest.serverless.providers.aws.request).toHaveBeenCalledWith(
+          'CloudFormation',
+          'describeStacks',
+          jasmine.objectContaining({StackName: 'testStackName'}), 'testStage', 'testRegion'
+        );
+
+        done();
+      });
+    });
+  });
+});

src/index.js

@@ -1,12 +1,15 @@
 'use strict';
 const documentation = require('./documentation');
 const models = require('./models');
+const fs = require('fs');
+const downloadDocumentation = require('./downloadDocumentation');
 
 class ServerlessAWSDocumentation {
   constructor(serverless, options) {
     this.serverless = serverless;
     this.options = options;
-    this.provider = 'aws'
+    this.provider = 'aws';
+    this.fs = fs;
 
     Object.assign(this, models);
     Object.assign(this, documentation());
@@ -18,13 +21,29 @@ class ServerlessAWSDocumentation {
 
     this._beforeDeploy = this.beforeDeploy.bind(this)
     this._afterDeploy = this.afterDeploy.bind(this)
+    this._download = downloadDocumentation.downloadDocumentation.bind(this)
 
     this.hooks = {
       'before:package:finalize': this._beforeDeploy,
       'after:deploy:deploy': this._afterDeploy,
+      'downloadDocumentation:downloadDocumentation': this._download
     };
 
     this.documentationParts = [];
+
+    this.commands = {
+        downloadDocumentation: {
+            usage: 'Download API Gateway documentation from AWS',
+            lifecycleEvents: [
+              'downloadDocumentation',
+            ],
+            options: {
+                outputFileName: {
+                    required: true,
+                },
+            },
+        }
+    };
   }
 
   beforeDeploy() {

src/index.spec.js

@@ -84,6 +84,7 @@ describe('ServerlessAWSDocumentation', function () {
       expect(this.plugin.hooks).toEqual({
         'before:package:finalize': this.plugin._beforeDeploy,
         'after:deploy:deploy': this.plugin._afterDeploy,
+        'downloadDocumentation:downloadDocumentation': this.plugin._download,
       });
     });