serverless-import-swagger

Import functions from OpenAPI spec file to serverless.yml of Serverless Framework

Note

In v0.2, there are breaking changes.
Please be careful when upgrading.

Install

$ npm install -g serverless-import-swagger

Usage

Quick start

Add a file named openapi.yaml on application root directory.
Then, run following command and serverless-import-swagger generate service of Serverless Framework.

$ sis

Command option.

Usage: sis [options]

Import functions from OpenAPI spec filet to serverless.yml

Options:
  -V, --version                 output the version number
  -C, --config <path>           Specify config file path. (defailt "./sis.config.json")
  -s, --service-name <string>  Specify service name. (default "service")
  -i, --input [path]            Specify OpenAPI file path. (defailt "./openapi.ya?ml")
  -o, --out-dir <path>          Specify dist directory of services. (default "./")
  -c, --common <path>           Specify common config of serverless file path. (default "./serverless.common.ya?ml")
  -f, --force                   If add this option, overwriten serverless.yml by generated definitinos.
  -h, --help                    output usage information

Example

$ sis -i /path/to/swagger.yml -c /path/to/serverless.common.yml -o ./src

sis.config.json

You can set options using a configuration file. By default, sis.config.json will be applied automatically if it exists.

{
  "all": <boolean>, // Specify whether to target all of the document. (default true)
  "serviceName": <string>, // Specify service name. (default "service")
  "basePath": <boolean | { "servicePrefix": <string> }>, // Specify base path mode enabled. (defualt false)
  "input": <string[] | null>, // Specify OpenAPI file path. (defailt "./openapi.ya?ml")
  "outDir": <string | null>, // Specify dist directory of services. (default "./")
  "common": <string | null>, // Specify common config of serverless file path. (default "./serverless.common.ya?ml")
  "force": <boolean>, // Specify overwrite enabled. (default false)
  "options": {
    "cors": <boolean | any>, // Specify the addition of cors setting. Accept the format of the Serverless Framework's cors settings. (default false) 
    "optionsMethod": <boolean>, // Specify addition of options method for the path. (default false)
    "authorizer": <string | null>, // Specify AWS_IAM authorizers or custom authorizers. (default null)
    "operationId": <boolean> // Specify use of operationId in function name. (default false)
  }
}

The default values ​​apply to items not set.

Base path mode

Due to the limitations of CloudFormation, it is not possible to create a service with a large number of endpoints.
The base path mode splits services based on the top level path.
If base path mode is set to true, the top level path will be the service name. If you specify servicePrefix, a prefix can be added before the service name.

x-sis-config

You can use the extension of x-sis-config to write config in the spec file.
The config at the top level apply to the entire file, and the config at operation parameters apply only to that function.
If you disable all in config, only operations for which x-sis-config is set are imported.

Caution

Serverless depends on constraints of amazon web service.
For example...

• The maximum number of CloudFormation resources is 200. Therefore, APIs that contain many paths need to be divided using --base-path mode.
• The function name of AWS Lambda must be 64 characters or less. For that reason, if long function names are generated, they can not be deployed.
• API Gateway requires that path parameters in the same hierarchy be unique. Serverless also suffers from similar restrictions.