@carlsberg/openapi-aws-extensions/README.md

A library that adds API Gateway extensions to OpenAPI specification files

# OpenAPI AWS API Gateway Extensions

> A library and CLI that add API Gateway extensions to OpenAPI specification files

### Disclaimer

This project is _work in progress_ and isn't production ready, it doesn't support all [API Gateway extensions for OpenAPI](https://docs.aws.amazon.com/apigateway/latest/developerguide/api-gateway-swagger-extensions.html) and lacks customization features. Use at your discretion.

## Installation

To install the CLI tool:

```shell
$ npm install --global @carlsberg/openapi-aws-extensions-cli
$ openapi-aws-extensions-cli --version
0.0.1
```

To install the library to use on your project:

```
$ npm install --save @carlsberggbs/openapi-aws-extensions
```

## Usage

```
$ openapi-aws-extensions-cli --help

Usage: openapi-aws-extensions-cli -w [num] -h [num]

Options:
  --help                Show help                                      [boolean]
  --version             Show version number                            [boolean]
  --inputFile           The OpenAPI specification file to add extensions to
                                                             [string] [required]
  --outputFile          The file to output the resulting OpenAPI specification
                                                                        [string]
  --outputFormat        The output format (either JSON or YAML), if different
                        from input                    [string] [default: "yaml"]
  --lambdaFunctionName  The AWS Lambda Function name to use on the extension's
                        URI                                  [string] [required]
  --cors                Enable CORS                   [boolean] [default: false]
```

## Options

| Name                 | Description                                                                                                             | Default                      |
| -------------------- | ----------------------------------------------------------------------------------------------------------------------- | ---------------------------- |
| `inputFile`          | The path to the OpenAPI specification file to which to add AWS extensions                                               | `null`                       |
| `outputFile`         | The path to where to output the extended OpenAPI specification. If none is specified, the result is outputted to stdout | `null`                       |
| `outputFormat`       | The format of the outputted OpenAPI specification                                                                       | `yaml` or `inputFile` format |
| `lambdaFunctionName` | An AWS Lambda Function name to use in the `x-amazon-apigateway-integration` extension                                   | `null`                       |
| `cors`               | Adds default CORS headers to any `OPTIONS` methods to enable CORS                                                       | `false`                      |

## Reference

- [API Gateway extensions for OpenAPI](https://docs.aws.amazon.com/apigateway/latest/developerguide/api-gateway-swagger-extensions.html)