serverless-swagger-api
Version:
[](https://travis-ci.org/drg-adaptive/serverless-swagger-api) [](https://codeclimat
101 lines (68 loc) • 4.27 kB
Markdown
# Serverless Swagger API
[](https://travis-ci.org/drg-adaptive/serverless-swagger-api)
[](https://codeclimate.com/github/drg-adaptive/serverless-swagger-api/maintainability)
[](https://badge.fury.io/js/serverless-swagger-api)
[](https://app.fossa.io/projects/git%2Bgithub.com%2Fdrg-adaptive%2Fserverless-swagger-api?ref=badge_shield)
This is a serverless plugin that simplifies the process of creating an AWS API Gateway from a swagger file.
## Installation
```bash
yarn add --dev serverless-swagger-api
```
## Configuration
### Lambda Functions
You must manually create your own lambda functions in the serverless configuration. Once the methods are created, they will be referenced in the swagger file.
### Swagger File
Add a `x-lambda-name` property to every path method to bind a part of the api to a lambda.
```yaml
paths:
/testPath:
get:
x-lambda-name: TestPathLambdaFunction
...
```
#### CORS Configuration
Add a `x-cors` property to the path you want to add CORS options responses to.
```yaml
paths:
/testPath:
x-cors: true
```
If you want to specify a specific attribute, provide one of the following properties
| Property | Description | Default |
| -------- | ----------------------------------- | ------------------------------------------------------------- |
| origin | A string specifying allowed origins | \* |
| headers | An array of headers to be allowed | Constructed from the parameters property of every path method |
| methods | An array of methods to be allowed | Constructed by looking at all methods defined for a path |
### Plugin Settings
Now you need to tell the swagger api plugin about your configuration file. Add a `swaggerApi` property to the custom section of your serverless configuration. You can add as many apis as you want by adding children to the `swaggerApi.apis` property.
#### updateDeployments
Will automatically update API gateway deployments if not set to `false`.
#### usePackageVersion
The `info.version` value in your OpenAPI file will be overwritten with the version in `package.json`.
#### apis
An object containing all of the APIs to be defined in this stack.
```yaml
custom:
swaggerApi:
updateDeployments: true
usePackageVersion: true
apis:
PrimaryApi:
Name: ${self:provider.stage}-${self:service}-PrimaryApi
Body: ${file(./some-swagger-file.yaml)}
Lambda: ExampleLambdaFunction
Stage: dev
```
##### Properties
Each API object has the following properties
| Name | Required | Description |
| ------ | -------- | ---------------------------------------------------------------------------------------------------------------------------- |
| Name | Yes | Name of the API that will be used as the `Name` parameter when creating the `AWS::ApiGateway::RestApi` CloudFormation object |
| Body | Yes | The swagger/openapi file that defines the API |
| Stage | Yes | The name of the API Gateway stage that will be created |
| Lambda | No | Default lambda name that will be used if `x-lambda-name` isn't provided on a path |
## Created Resources
### IAM Roles
An IAM role is created for each API with the name `PrimaryApiServiceRole`
## License
[](https://app.fossa.io/projects/git%2Bgithub.com%2Fdrg-adaptive%2Fserverless-swagger-api?ref=badge_large)