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

plugins:
  - '@nightapes/serverless-openapi'

To generate api run

serverless openapi

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

serverless openapi -o openapi.yaml

or set it via serverless yaml

custom:
  openapi:
    out: openapi.yaml

Add basic info and tags

Under custom add

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

Example for request and response schema

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

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'

Default respsonse

You can set a default response via

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

Enable the default response per function via

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

Parameters

Following format to add paramters is supported. See SLS Doc

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

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"

Authorization

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

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

Inside your function:

...
  events:
    - http:
        authorizer:
          name: authorizer        
...

TODO

• Servers
• Authorizer