Arazzo Generator for Serverless Framework

Document your Serverless Framework API workflows with the OpenAPI Arazzo Workflow Spec.

This will generate an OpenAPI Arazzo Specification (1.0.1) for your Serverless Framework APIs. This requires the Serverless OpenAPI Documenter plugin to be installed and used, as the Arazzo Specification makes use of the generated OpenAPI Document.

Install

This plugin works for Serverless Framework (3.x and 4.x) and only supports node.js 20 and up.

To add this plugin to your package.json:

Using npm:

npm install --save-dev serverless-arazzo-workflows

Using the plugin:

Next you need to add the plugin to the plugins section of your serverless.yml file.

plugins:
  - serverless-openapi-documenter
  - serverless-arazzo-workflows

Note: serverless-openapi-documenter is required for this to work.

This plugin can be used to generate Arazzo Specifications and to Run a generated Arazzo Specification.

To generate the specification, you should see:

• Generation

To run a specification, you should look at:

• Running

Generating the Arazzo Specification file

To generate an Arazzo Specification, you can call the plugin from the CLI like:

serverless arazzo generate -f json

Options:

--format -f  Whether to output the Arazzo Specification as json or yaml. Default: json
--output -o  The name of the Arazzo Specification file. Default: arazzo.json
--source -s  The default openAPI source file. Default: openapi.json

Configuration

You can configue your serverless file in two ways:

1. All under the custom property of your Serverless File
2. A mixture of the custom property and the Event Handlers

For the first one, this can allow you to seperate it out to a separate file like: serverless-arazzo.yml and then importing it like:

custom:
  arazzo: ${file(serverless-arazzo.yml):arazzo}

See Configuration via the custom property on how to configure by this method.

If you prefer, you might wish to add Configuration on each Handler. You can also seperate the documentation out into a separate file:

custom:
  arazzo: ${file(serverless-arazzo.yml):arazzo}

functions:
  myFunc:
    events:
      - http:
          path: getStuff
          method: get
          documentation: ${file(serverless-arazzo.yml):endpoints.myFunc}

To configue this second way, see Configuration via each handler.

Configuration via the custom property

To configure this plugin to generate a valid OpenAPI Arazzo Specification, you'll need to modify the custom section of your serverless.yml file.

The custom section of your serverless.yml can be configured as below:

custom:
  arazzo:
    info:
      title:
      summary:
      description:
      version:
    sourceDescriptions:
      - name:
        url:
        type:
    workflows:
      - workflowId:
        steps:
          - stepId:

info

Mostly everything is optional in the info object. If you don't provide a title, it'll pull it from your service name, if you don't provide a version, it'll default to '1'.

sourceDescriptions

This section is optional. It allows you to document any extra OpenAPI or Arazzo Specification files that your workflows and steps may require. If you do not document this section, it will end up with a default of:

sourceDescriptions:
  - name: arazzo.info.title
    url: ./openapi.json
    type: openapi

That is, that it generates the name property from the title property of the info object (or the one that is generated for you if you omitted the info object).

The url will be that of a local openapi.json file, this is what the Serverless OpenAPI Documenter generates by default. This can be changed by the CLI by providing a source argument with the path to a different OpenAPI file. To make this usable, this should really be an accessible URL, so you should switch the --source CLI input to be the final resting place of the specification (an S3 bucket perhaps), for running locally it will be fine to keep it as a local location.

If you do provide this section, then any further additions will be added to that of the default sourceDescription. This is useful if you need to incorporate a step or workflow that resides in a different API (perhaps a Login service).

workflows

Workflows describe the steps to be taken across one or more APIs to achieve an objective.

workflows:
  - workflowId:
    summary:
    description:
    inputs:
    dependsOn:
    successActions:
    failureActions:
    outputs:
    parameters:
    steps:

Workflows comprise of one or many workflow objects, one workflow might be for logging in, another might be for resetting a password. They comprise of steps, where one step might be to call an endpoint to login and the next step would be to call an endpoint that allows a user to change their name.

Each workflow object requires a workflowId and a set of steps. workflowId should conform to the Regex [A-Za-z0-9_\-]+ and should be unique across the Arazzo Specification.

inputs

inputs is a JSON Schema of the various inputs you will need for each step e.g.

- workflowId: loginUserWorkflow
  summary: Allow a user to login
  description: This workflow describes logging in a user.
  inputs:
    type: object
    properties:
      username:
        type: string
      password:
        type: string

The inputs here will be used in a login step and can be verified by this JSON Schema. If you are to be usng the runner part of this plugin (see Running), then the inputs should map to the input file (see Input File).

steps

Describes a single workflow step which MAY be a call to an API operation (OpenAPI Operation Object) or another Workflow Object.

steps:
  - stepId:
    description:
    operationId:
    parameters:
      - name:
        in:
        value:
    requestBody:
      contentType:
      payload:
    successCriteria:
      - condition:

Each step object requires a stepId which conforms to the Regex [A-Za-z0-9_\-]+. The operationId should point to an operationId within an OpenAPI document that is registered within the sourceDescriptions array. If you are using multiple OpenAPI files within the sourceDescriptions array, then you will need to reference the operationId via: $sourceDescriptions.<name>.<operationId> e.g.

sourceDescriptions:
  - name: loginOpenAPI
    url: ./openapi.json
    type: openapi
  - name: contactOpenAPI
    url: ./contactOpenAPI.json
    type: openapi
workflows:
  ...
  steps:
    - stepId: loginUser
      operationId: $sourceDescriptions.loginOpenAPI.login
      ...
    - stepId: changeUserName
      operationId: $sourceDescriptions.contactOpenAPI.updateUser

parameters map to what must be passed into the referenced operation of the OpenAPI document, they map to the inputs described in the workflow section` e.g.

- workflowId: loginUserWorkflow
  summary: Allow a user to login
  description: This workflow describes logging in a user.
  inputs:
    type: object
    properties:
      username:
        type: string
      password:
        type: string
  stepes:
    - stepId: loginUser
      parameters:
        - name: username
          in: query
          value: $inputs.username

requestBody is very similar, the contentType should map to that of the operationId that is referenced in the OpenAPI document and the value map to the inputs referenced in the workflow.

For successCriteria, it is probably worth reading through the Arazzo Specification for Criterion objects, but this can be as simple as

successCriteria:
  - condition: $statusCode == 200

Where it is checking the statusCode of the operation to match 200.

Extended Fields

You can also add extended fields to most of the documentation objects:

custom:
  arazzo:
    info:
      x-other-field: This is an extended field

These fields must have x- before them, otherwise they will be ignored:

custom:
  arazzo:
    info:
      other-field: This is not an extended field

other-field here will not make it to the generated Arazzo document.

Configuration via each handler

Documenting via each handler does carry over some of the same way we document via the custom property:

custom:
  arazzo:
    info:
      title:
      summary:
      description:
      version:
    sourceDescriptions:
      - name:
        url:
        type:

This remains the same as what is discussed within Configuration via the custom property.

• See info for how to document Info
• See sourceDescriptions

Workflows is where it starts to differ:

Workflows using handlers to document steps

Most of the workflow property remains the same, however we no longer document steps here.

custom:
  arazzo:
    ...
    workflows:
      - workflowName:
        workflowId:
        summary:
        description:
        inputs:
        dependsOn:
        successActions:
        failureActions:
        outputs:
        parameters:

This still matches up to workflows (without steps). How we document steps, now moves to the handlers:

custom:
  arazzo:
    ...
    workflows:
      - workflowName: addPet
        workflowId:
        ...

functions:
  addPet:
    handler: handler.addPet
    events:
      - http:
          ...
          arazzo:
            ...

Steps using handlers

To move documentation generation to a step, your configuration should now look like this

functions:
  addPet:
    handler: handler.addPet
    events:
      - http:
          ...
          arazzo:
            workflows:
              - workflowName: addPet
                stepNumber: 1
                stepId:
                operationId:
                operationPath:
                workflowId:
                parameters:
                requestBody:
                successCriteria:
                onSuccess:
                onFailure:
                outputs:

Much of this is unchanged from Steps, however, we are adding a stepNumber and workflowName.

workflowName must match up to a workflow defined in your custom section for workflows.

stepNumber is the order of which the step should be run, steps start from 1, so the above example would be the first step in the addPet workflow.

If you don't provide either a operationId, operationPath or a workflowId for the step, the operationId will be set to the name of your function. In the above example, the operationId would become addPet.

Validator

Validation for the Araazo Specification is done by Redocly.

Rules

I have configured the validator to use these Rules:

• struct
• sourceDescriptions-name-unique
• sourceDescriptions-type
• stepId-unique
• workflowId-unique

However, you can configure your own rules from the ruleset available on the Redocly site. To do this, you will need to create a redocly-arazzo.json file within an options folder. The file should look like:

{
  "struct": "error",
  "sourceDescriptions-name-unique": "error",
  "sourceDescriptions-type": "error",
  "stepId-unique": "error",
  "workflowId-unique": "error"
}

Running the Arazzo Specification

For now, I recommend using the Redocly CLI to run your Arazzo Workflows.