Serverless Express Swagger JSDocs

!Serverless_Express_Swagger_JSDocs

Add documentation to a serverless Express API using JSDoc.

buildDocs.js

import swaggerJsdoc from 'swagger-jsdoc'
import writeJsonFile from 'write-json-file'
import definition from '../src/docs/swaggerDef'

const options = {
  definition,
  apis: ['src/docs/*.yml', 'src/routes/v1/*.js']
};

const openapiSpecification = swaggerJsdoc(options);

writeJsonFile('src/docs/swagger.json', openapiSpecification);

buildspec.yml

version: 0.1
phases:
    install:
        commands:
        - echo "Installing dependencies..."
        - npm ci
        - npx serverless plugin install
            --name serverless-webpack
    pre_build:
        commands:
    build:
        commands:
        - echo "Building..."
        - npm run build-docs
        - npm run build
    post_build:
        commands:
        - echo "Syncing files to S3..."
        - aws s3 sync ./.serverless "s3://bucket"
            --delete

components.yml

components:
  schemas:
    NumClients:
      type: object
      properties:
        clients:
          type: number
      example:
        clients: 1423

    Error:
      type: object
      properties:
        code:
          type: number
        message:
          type: string

  responses:
    NotFound:
      description: Not found
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          example:
            code: 404
            message: Not found

docs.controller.js

import HTTPStatus from 'http-status';
import specs from '../docs/swagger.json'

export async function getDocs(req, res, next) {
  try {
    return res.status(HTTPStatus.OK).json(specs);
  } catch (err) {
    err.status = HTTPStatus.BAD_REQUEST;
    return next(err);
  }
}

swagger.json

{
	"paths": {},
	"components": {
		"schemas": {
			"NumClients": {
				"type": "object",
				"properties": {
					"clients": {
						"type": "number"
					}
				},
				"example": {
					"clients": 1423
				}
			},
			"Error": {
				"type": "object",
				"properties": {
					"code": {
						"type": "number"
					},
					"message": {
						"type": "string"
					}
				}
			}
		},
		"responses": {
			"NotFound": {
				"description": "Not found",
				"content": {
					"application/json": {
						"schema": {
							"$ref": "#/components/schemas/Error"
						},
						"example": {
							"code": 404,
							"message": "Not found"
						}
					}
				}
			}
		}
	},
	"tags": []
}

swaggerDef.js

import { version, description } from '../../package.json'

const swaggerDef = {
  openapi: '3.0.0',
  info: {
    title: 'Example',
    version,
    description,
  }
};

export default swaggerDef

test.routes.js

/**
 * Test Routes
 */

import { Router } from 'express';

import * as TestController from '../../controllers/test.controller';

const routes = new Router();

/**
* CRUD
*/
routes.get('/db', TestController.getDb);

export default routes;

/**
 * @swagger
 * tags:
 *   name: Test
 *   description: Test endpoint for docs
 */

/**
 * @swagger
 * /test:
 *   get:
 *     summary: Get test
 *     description: Get information on the database as a test case for the docs
 *     tags: [Test]
 */