API to Cloud

This tool injects cloud specific integration points to API definition in Swagger.

Installing

This is a NodeJS module available through the npm register.

Installation is done using the npm install command:

$ npm install @antklim/api-to-cloud

Usage

After installation api-to-cloud CLI will be available in node_modules/.bin.

Usage: api-to-cloud [options]


  Options:

    -V, --version             output the version number
    -a, --api <path>          API definition file path
    -i, --integration <path>  API integration file path
    -o, --output <path>       path to output extended API file
    -c, --cloud [cloud]       cloud provider [AWS], default 'AWS'
    -f, --format [format]     output file format [yaml|yml|json], default 'yaml'
    -h, --help                output usage information

Run the following command to produce swagger file with AWS specific integration points:

$ node_modules/.bin/api-to-cloud --api test-api.yaml \
                                 --integration test-integration.yaml \
                                 --output aws.yaml

Programmatic API

parser

The parser module provides utilities for parsing of API and integration point descriptions. Currently supported two formats: YAML and JSON. It can be accessed using:

const {parser} = require('@antklim/api-to-cloud')

parser.parse(file)

• file String - path to the file to parse
• Returns: Promise - resolves with the file data parsed into object

Example:

parser.parse('input.yaml')
  .then(data => console.log(JSON.stringify(data, null, 2)))
  .catch(err => console.error(err))

parser.for(format)

• format String - file format to parse
• Returns: Function - parser function or null

encoder

The encoder module provides utilities for formatting and storing of API definition. Currently supported two formats: YAML and JSON. It can be accessed using:

const {encoder} = require('@antklim/api-to-cloud')

encoder.save(data, file, format)

• data Object - data to write to file
• file String - path to file to write
• format String - format to save payload in
• Returns: Promise - resolves when payload written into the file

Example:

encoder.save({'foo': 'bar'}, 'example.yaml', 'yaml')
  .then(() => console.log('Payload written into \'example.yaml\''))
  .catch(err => console.error(err))

encoder.for(format)

• format String - file format to encode to
• Returns: Function - encoder function or null

integrator

The integrator module provides utilities for merging pure API description in Swagger format with cloud specific integration points. It can be accessed using:

const {integrator} = require('@antklim/api-to-cloud')

integrator.extend(api, integrationPaths, cloud)

• api Object - Swagger API definition
• integrationPaths Object - cloud integration points to add to API
• cloud String - target cloud provider, [AWS]
• Returns: Object - extended Swagger API (API + integrations)

Format of the integration points object:

path:
  method:
    integrationPoint: ...

Example of integration object:

/pets:
  get:
    x-amazon-apigateway-integration:
      responses:
        default:
          statusCode: "200"
      requestTemplates:
        application/json: "{\"statusCode\": 200}"
      passthroughBehavior: "when_no_match"
      type: "mock"
  post:
    x-amazon-apigateway-integration:
      responses:
        default:
          statusCode: "200"
      requestTemplates:
        application/json: "{\"statusCode\": 200}"
      passthroughBehavior: "when_no_match"
      type: "mock"
/pets/{petId}:
  get:
    x-amazon-apigateway-integration:
      responses:
        default:
          statusCode: "200"
      requestTemplates:
        application/json: "{\"statusCode\": 200}"
      passthroughBehavior: "when_no_match"
      type: "mock"

integrator.cleanApi(api, removables)

• api Object - Swagger API definition
• removables Array - the list of paths to remove from the API description
• Returns: Object - API definition cleaned from removables

Built With

• js-yaml - YAML parser/encoder for JavaScript
• ava - Futuristic test runner
• ESLint - JavaScript linting utility
• testdouble - JavaScript test mocking library

Authors

• Anton Klimenko

License

This project is licensed under the MIT License - see the LICENSE file for details