Serverless About Plugin

An about endpoint to describe your lambdas.

Requirements:

• Serverless v1.12.x or higher.
• AWS provider

How it works

About creates a new endpoint (named __about by default) which can be called to provide a json summary of the current purpose of each lambda.

Setup

Install via npm in the root of your Serverless service:

npm install serverless-plugin-about --save-dev

• Add the plugin to the plugins array in your Serverless serverless.yml:

plugins:
  - serverless-plugin-about

• Add a about property to all the events in all the functions you want to be documented.

functions:
  hello:
    events
      - http:
          path: /schema/{TypeID}
          method: get
          private: false
          about:
            purpose: Output of the schema for a type of data
            params: TypeID: the type of data
      - http:
          path: /schema/{TypeID}/{FieldID}
          method: get
          private: false
          about:
            purpose: Output of the schema for a field
            params: TypeID and FieldID

• Add additional properties to trigger the output of a full description for each lambda

         about:
            purpose: Output of the schema for a type of data
            params: TypeID: the type of data
            id: fullschema
            lastUpdated: []

Note that the ok and lastUpdated are reserved and will automatically be populated, as follows: o lastUpdated is the date.time at which the about was ran

• about to be able to invoke lambdas requires the following Policy Statement in iamRoleStatements:

iamRoleStatements:
  - Effect: 'Allow'
    Action:
      - 'lambda:InvokeFunction'
    Resource:
    - Fn::Join:
      - ':'
      - - arn:aws:lambda
        - Ref: AWS::Region
        - Ref: AWS::AccountId
        - function:${self:service}-${opt:stage, self:provider.stage}-*

Options

• cleanFolder (default true)
• memorySize (default 128)
• name (default ${service}-${stage}-about-plugin)
• timeout (default 10 seconds)
• endpoint (default __about)

custom:
  about:
    cleanFolder: false,
    memorySize: 256
    name: 'show_me_info'
    timeout: 20
    endpoint: _show_info

• define a custom header for the about to give the output some context

    endpoint: __about
    format:
      schemaVersion: 1
      name: A great system that uses about
      systemCode: greatsys
      components: []

Note that components is reserved and is used to identify the location into which the array of lambda infomation responses will be placed

Artifact

If you are doing your own package artifact set option cleanFolder to false and run serverless package. This will allow you to extract the healthcheck NodeJS lambda file from the _healthcheck folder and add it in your custom artifact logic.

Contribute

Help us making this plugin better and future proof.

• Clone the code
• Install the dependencies with npm install
• Create a feature branch git checkout -b new_feature
• Lint with standard npm run lint

License

This software is released under the MIT license. See the license file for more details.