Serverless OpenAPI Joi Plugin

Serverless plugin for creating OpenAPI v3 specifications with Joi validation.

This plugin allows you to define input validation for your serverless API endpoints and generates OpenAPI definitions from validation rules, which can be either saved somewhere or served directly as an endpoint in the API itself.

See full example project boilerplate here: anttiviljami/serverless-openapi-joi-boilerplate

Philosophy

As developers, we are lazy when it comes to writing documentation.

Even with nice modern tools like the OpenAPI standard (previously known as Swagger) which allows us to auto-generate API docs and clients from formatted specification documents, they are tideous to write and thus often out-of-date.

The best way to make sure API documentation stays up-to-date is to generate it from API code itself and actively use the generated API definition in our development workflows.

With serverless-openapi-joi, OpenAPI specification is generated as a by-product of defining Joi input validation rules to our API endpoints. As a bonus, we get nice machine- and human-readable Boomified validation errors.

Inspired by hapi-swagger

Example

Install the plugin:

npm install --save serverless-openapi-joi

In serverless.yml, add the plugin and define your api endpoints:

1plugins:
2  - serverless-openapi-joi
3
4functions:
5  api:
6    handler: index.handler
7    events:
8      - http:
9          path: swagger.json
10          method: get
11          private: true
12      - http:
13          path: pets
14          method: get
15          private: true
16      - http:
17          path: pets/{id}
18          method: get
19          private: true
20      - http:
21          path: pets
22          method: post
23          private: true
24      - http:
25          path: pets/{id}
26          method: patch
27          private: true
28      - http:
29          path: pets/{id}
30          method: delete
31          private: true

In the handler:

1import OpenAPIHandler from 'serverless-openapi-joi/handler'; // ES6 syntax
2// or
3const OpenAPIHandler = require('serverless-openapi-joi/handler').default; // CommonJS syntax

1const openapi = new OpenAPIHandler({
2  info: {
3    title: 'Example Pet API',
4    description: 'Example CRUD API with Serverless OpenAPI Joi plugin',
5    version: '0.1.0',
6  },
7  servers: [{ url: 'https://5oipict212.execute-api.eu-west-1.amazonaws.com/dev' }],
8  swaggerEndpoint: '/swagger.json',
9  routes, // defined below
10});
11
12export async function handler(event) {
13  return openapi.handler(event);
14  // NOTE: you should catch any errors from your handler
15  // serverless-openapi-joi throws validation errors as Boom errors
16}

Validation models are defined using Joi:

1import Joi from '@hapi/joi';
2
3const validation = {
4  petId: Joi.number().integer()
5    .description('Unique identifier for pet in database')
6    .example(1)
7    .label('PetId'),
8
9  petPayload: Joi.object({
10    name: Joi.string()
11      .description('Name of the pet')
12      .example('Garfield')
13      .label('PetName'),
14  }).label('PetPayload'),
15
16  limit: Joi.number().integer().positive()
17    .description('Number of items to return')
18    .example(25)
19    .label('QueryLimit'),
20
21  offset: Joi.number().integer().min(0)
22    .description('Starting offset for returning items')
23    .example(0)
24    .label('QueryOffset'),
25};

Routes define API operations using validation rules (see docs):

1const routes = [
2  {
3    method: 'GET',
4    path: '/pets',
5    handler: getPets, // event is passed through to a standard serverless handler function after validation
6    summary: 'List pets',
7    description: 'Returns all pets in database',
8    tags: ['pets'],
9    validation: {
10      queryStringParameters: {
11        limit: validation.limit,
12        offset: validation.offset,
13      },
14    },
15    responses: {
16      200: { description: 'List of pets in database' },
17    },
18  },
19  {
20    method: 'GET',
21    path: '/pets/{id}',
22    handler: getPetById,
23    summary: 'Get a pet by its id',
24    description: 'Returns a pet by its id in database',
25    tags: ['pets'],
26    validation: {
27      pathParameters: {
28        id: validation.petId,
29      },
30    },
31    responses: {
32      200: { description: 'Pet object corresponding to id' },
33      404: { description: 'Pet not found' },
34    },
35  },
36  {
37    method: 'POST',
38    path: '/pets',
39    handler: createPet,
40    summary: 'Create pet',
41    description: 'Crete a new pet into the database',
42    tags: ['pets'],
43    validation: {
44      payload: validation.petPayload,
45    },
46    responses: {
47      201: { description: 'Pet created succesfully' },
48    },
49  },
50  {
51    method: 'PATCH',
52    path: '/pets/{id}',
53    handler: updatePetById,
54    summary: 'Update pet',
55    description: 'Update an existing pet in the database',
56    tags: ['pets'],
57    validation: {
58      pathParameters: {
59        id: validation.petId,
60      },
61      payload: validation.petPayload,
62    },
63    responses: {
64      200: { description: 'Pet updated succesfully' },
65      404: { description: 'Pet not found' },
66    },
67  },
68  {
69    method: 'DELETE',
70    path: '/pets/{id}',
71    handler: deletePetById,
72    summary: 'Delete a pet by its id',
73    description: 'Deletes a pet by its id in database',
74    tags: ['pets'],
75    validation: {
76      pathParameters: {
77        id: validation.petId,
78      },
79    },
80    responses: {
81      200: { description: 'Pet deleted succesfully' },
82      404: { description: 'Pet not found' },
83    },
84  },
85];

The OpenAPI specification for your API gets automatically generated and served at /swagger.json!

You can also access the specification object anywhere programmatically using the getSpecification() method.

OpenAPI specifications can be easily viewed using tools like Swagger UI:

Documentation

View the documentation here: DOCS.md