apeman-app-rest/lib/specifying/rest_spec.js

apeman app to handle restful endpoint.

/**
 * Describe create endpoint.
 * @function restSpec
 * @returns {Object} - OAI 2.0 Path object for create endpoint.
 * @see https://github.com/OAI/OpenAPI-Specification/blob/master/versions/2.0.md#pathItemObject
 */
'use strict'

const UrlConstants = require('../constants/url_constants')
const requestOfModel = require('../naming/request_of_model')
const responseOfModel = require('../naming/response_of_model')
const idOfModel = require('../naming/id_of_model')
const stringcase = require('stringcase')

/** @lends restSpec */
function restSpec (model, options = {}) {
  const NAME = stringcase.camelcase(model.$name)
  const PASCAL_NAME = stringcase.pascalcase(NAME)
  const PATHNAME = options.pathname || '/'

  const LIST_RES_NAME = responseOfModel(NAME, 'list')
  const CREATE_REQ_NAME = requestOfModel(NAME, 'create')
  const CREATE_RES_NAME = responseOfModel(NAME, 'create')
  const ONE_RES_NAME = responseOfModel(NAME, 'one')
  const UPDATE_REQ_NAME = requestOfModel(NAME, 'update')
  const UPDATE_RES_NAME = responseOfModel(NAME, 'update')
  const DESTROY_RES_NAME = responseOfModel(NAME, 'destroy')
  const ID_NAME = idOfModel(NAME)

  let _def = (name) => ({ $ref: `#/definitions/${name}` })
  let _param = (name) => ({ $ref: `#/parameters/${name}` })

  return {
    swagger: '2.0',
    info: {
      title: `${PASCAL_NAME} RESTFul Endpoint`,
      description: `RESTFul endpoint for ${NAME} model with [JSON API](${UrlConstants.JSONAPI_URL}) format.`
    },
    consumes: [
      'application/json'
    ],
    produces: [
      'application/json'
    ],
    paths: {
      [`${PATHNAME}`]: {
        /**
         * List action
         */
        get: {
          summary: `Fetch collection of ${NAME}`,
          description: `Fetch collection of ${NAME} model.`,
          operationId: `list${PASCAL_NAME}`,
          parameters: [
            // {
            //     name: `filter`,
            //     in: `query`
            // },
            // {
            //     name: `sort`,
            //     in: `query`
            // },
            {
              name: 'page[number]',
              description: 'Number of page, starts with 1',
              in: 'query',
              type: 'integer'
            },
            {
              name: 'page[size]',
              description: 'Number of item in each page',
              in: 'query',
              type: 'integer'
            }
          ],
          responses: {
            200: {
              description: `List result for ${NAME}`,
              schema: _def(LIST_RES_NAME)
            }
          }
        },
        /**
         * Create action
         */
        post: {
          summary: `Create a ${NAME}`,
          description: `Create a new ${NAME} model.`,
          operationId: `create${PASCAL_NAME}`,
          parameters: [ {
            name: 'creating',
            in: 'body',
            description: `Request payload for ${NAME} create`,
            schema: _def(CREATE_REQ_NAME)
          } ],
          responses: {
            201: {
              description: `Successfully create a new ${NAME}`,
              schema: _def(CREATE_RES_NAME)
            }
            // TODO 400
          }
        }
      },
      [`${PATHNAME}/{${stringcase.snakecase(ID_NAME)} }`]: {
        get: {
          summary: `Fetch a ${NAME}`,
          description: `Fetch a single ${NAME} model by id`,
          operationId: `get${PASCAL_NAME}ById`,
          parameters: [
            _param(ID_NAME)
          ],
          responses: {
            200: {
              description: `One result for ${NAME}`,
              schema: _def(ONE_RES_NAME)
            }
            // TODO 404
          }
        },
        patch: {
          summary: `Update a ${NAME}`,
          description: `Update a ${NAME} by id.`,
          operationId: `update${PASCAL_NAME}ById`,
          parameters: [
            _param(ID_NAME),
            {
              name: 'updating',
              in: 'body',
              description: `Request payload for ${NAME} update`,
              schema: _def(UPDATE_REQ_NAME)
            }
          ],
          responses: {
            200: {
              description: `Successfully update ${NAME}`,
              schema: _def(UPDATE_RES_NAME)
            }
          }
        },
        delete: {
          summary: `Destroy a ${NAME}`,
          description: `Destroy a ${NAME} by id`,
          operationId: `destroy${PASCAL_NAME}ById`,
          parameters: [
            _param(ID_NAME)
          ],
          responses: {
            200: {
              description: `Successfully destroy ${NAME}`,
              schema: _def(DESTROY_RES_NAME)
            }
          }
        }

      }
    },
    parameters: {
      [ID_NAME]: {
        name: 'id',
        in: 'path',
        description: `ID of ${NAME}`,
        required: true,
        type: 'integer',
        format: 'int64'
      }
    },
    definitions: {
      [LIST_RES_NAME]: {
        type: 'object',
        properties: {
          meta: _def(LIST_RES_NAME + 'Meta'),
          data: _def(LIST_RES_NAME + 'Data'),
          links: _def(LIST_RES_NAME + 'Links')
        }
      },
      [LIST_RES_NAME + 'Data']: {
        type: 'array',
        items: {
          // FIXME
          'type': 'String'
        }
      },
      [LIST_RES_NAME + 'Meta']: {
        type: 'object',
        properties: {}
      },
      [LIST_RES_NAME + 'Links']: {
        type: 'object',
        properties: {}
      },
      [CREATE_REQ_NAME]: {
        type: 'object',
        properties: {}
      },
      [CREATE_RES_NAME]: {
        type: 'object',
        properties: {}
      },
      [ONE_RES_NAME]: {
        type: 'object',
        properties: {}
      },
      [UPDATE_REQ_NAME]: {
        type: 'object',
        properties: {}
      },
      [UPDATE_RES_NAME]: {
        type: 'object',
        properties: {}
      },
      [DESTROY_RES_NAME]: {
        type: 'object',
        properties: {}
      }
    }
  }
}

module.exports = restSpec