serverless-openapi

A simple openapi generator for serverless.

Support for serverless 2 and 3

The files is generated locally without any upload to aws apigateway.

Install

npm i -D @nightapes/serverless-openapi

Usage

Add plugin into your serverless.yml file

``yml
plugins:
- '@nightapes/serverless-openapi'
`

To generate api run

`bash
serverless openapi
`

If you want to change the format (json or yaml) or the file name use

`bash
serverless openapi -o openapi.yaml
`

or set it via serverless yaml

`yml
custom:
openapi:
out: openapi.yaml
`

$3

Under custom add

`yml
custom:
openapi:
title: 'my fancy openapi'
version: '1.0.0'
description: 'My description of the serverless api'
tags:
- name: Settings
description: Description
`

$3

Works only for aws http events, the request is the default serverless request schema.

`yml
functions:
create:
handler: posts.create
events:
- http:
path: v1/user-settings
method: put
tags:
- Settings
authorizer:
name: authorizer
scopes:
- admin
operationId: setUserSettings
cors: true
request:
schemas:
application/json:
schema: ${file(./your-schema.json)}
name: UserSettings
responseSchemas:
200:
application/json:
schema: ${file(./your-schema.json)}
name: UserSettings
description: 'UserSettings'
204:
application/json:
description: 'OK'
`

$3

You can set a default response via

`yml
custom:
openapi:
defaultResponse:
application/json:
schema: ${file(./apiError.type.json)}
description: 'Default api error'
name: ApiError
`

Enable the default response per function via

`yml
functions:
create:
handler: posts.create
events:
- http:
path: v1/user-settings
defaultResponse: true
`

$3

Following format to add paramters is supported. See SLS Doc

All parameters will be interpreted as string expect you add a parameterMapper.

`yml
functions:
create:
handler: posts.create
events:
- http:
path: posts/create
method: post
request:
parameters:
querystrings:
url: true
headers:
foo: false
paths:
bar: false
parameterMappers:
querystrings:
foo:
type: enum
options:
- csv
- json
bar:
type: number
# Optional
description: "Description"
# Optional
deprecated: true
# Optional
isArray: false
# Optional
format: "int32"
`

$3

At the moment only Bearer Auth with custom authorizer is supported
See: https://www.serverless.com/framework/docs/providers/aws/events/apigateway#http-endpoints-with-custom-authorizers

`yml
custom:
openapi:
securitySchemes:
"authorizer": // Name of the custom authorizer
type: http
scheme: bearer
bearerFormat: JWT
`

Inside your function:
`yml
...
events:
- http:
authorizer:
name: authorizer
...
``

TODO

- Servers
- Authorizer