http-doc

Creates your HTTP routes with ACL, data filtering and automatic documentation.

Features

• Documentation on routes or controllers
• Automatic OpenAPI documentation generator
• Access control management
• Plugin system to handle additional HTTP frameworks

Installation

Install http-doc with npm

npm install http-doc --save

or with yarn

yarn add http-doc

API instanciation

import { Api, collection } from 'http-doc'

const api = new Api({
  // options, see Api Options section
})

// Register routes
collection(
  'Users',
  router => {
    router.get('/', UserController.list, {
      // options, see Route Options section
    })
  },
  {
    title: 'Users',
    description: 'Managing users',
    prefix: '/users'
  }
)

// Apply configuration to your HTTP framework
api.setup()

Api Options

Parameter	Type	Description
app	object	HTTP framework instance
documentationPath	string	Documentation display path (Default: /swagger.json)
documentationAccess	function	Function used to restrict access to the documentation configuration file. (default: request => true)
driver	class	Provides plugin to use for HTTP framework interaction.
getUserAccess	string/array/function	List of user access list. Can be a single string, or a function returning a string or an array of strings.
monitor	boolean	Monitor all API calls (count, time metrics). Creates a set of monitoring API endpoints (See Monitoring section). (default: false)
monitorAccess	function	Function used to restrict access to the monitoring API. (default: request => true)
prefix	string	Prefix for all routes
schemasFolder	string	Path to folder containing all OpenAPI Schemas (default: schemas)

Route Options

Parameter	Type	Description
title	string	Endpoint name in documentation.
description	string	Endpoint description in documentation.
access	string/array/function	List of user access requirements. Can be a string, a function or an array of string or functions. Functions will return a boolean.
accepts	string/array/object	Restricts input with provided OpenAPI Schema. Can be a string (file path to schema), an object (OpenAPI schema), or an array of strings (file path to schema) or objects (direct schema or conditional object : {schema: String, handler: Function, description: String}). Validated schemas will be merged.
returns	object	List of possible returned data, by HTTP code.
returns.{code}	object	Object describing returned data.
returns.{code}.schema	string	OpenAPI Schema path, relative to schemasFolder Api configuration field.
returns.{code}.description	string	Description of returned data.
parameters.{name}	object	Object describing parameter.
parameters.{name}.schema	string	OpenAPI Schema path, relative to schemasFolder Api configuration field.
parameters.{name}.description	string	Description of parameter.

Access Control Lists

ACL is based on custom strings, like admin, users:list, per example. You define which permissions a user have, and he'll be able to access only routes with correct permissions.

Example

import { Api, collection } from 'http-doc'

const api = new Api({
  getUserAccess: request => {
    // Logged in user :
    /* {
      permissions: ['users:list', 'users:create']
    } */
    return request.user.permissions
  }
})

controller('Users', router => {
  router.get('/', listController, {
    access: 'users:list' // Will have access to this endpoint
  })
  router.post('/', createController, {
    access: ['admin', 'users:create'] // Will have access to this endpoint, because one of the requirements is fulfilled
  })
  router.put('/:id', updateController, {
    access: [
      'admin',
      'users:edit',
      request => request.params.id === request.user.id
    ] // Will not have access to this endpoint if he tries to edit another user
  })
})

OpenAPI Schemas

Input data and returned data filtering works with OpenAPI Schemas, stored where you want on your project folder in JSON format. References are relative to the provided schemas folder when initializing API.

Example :

{
  "type": "object",
  "required": ["name"],
  "properties": {
    "name": {
      "type": "string"
    },
    "address": {
      "$ref": "Address"
    },
    "age": {
      "type": "integer",
      "minimum": 0
    }
  }
}

More info on OpenAPI Schemas here.

Handled string formats :

• date
• date-time
• byte (or base64)
• email
• uuid
• objectid
• uri

Unsupported features :

• allOf
• anyOf
• oneOf
• not

Parameters

With parameters route configuration parameter, you can describe and filter parameters located in query, path, headers or cookies.

Example

import { collection } from 'http-doc'

controller('Users', router => {
  router.get('/', listController, {
    parameters: {
      page: { schema: 'params/Page', description: 'Page' },
      limit: { schema: 'params/Limit', description: 'Limit' }
    }
  })
})

Input data filtering

You can filter input data with accepts configuration field on routes.

Example

import { collection } from 'http-doc'
import UserGetFilter from '../UserGetFilter.json'

controller('Users', router => {
  router.get('/', listController, {
    accepts: 'UserListFilters'
  })
  router.get('/:id', listController, {
    accepts: UserGetFilter
  })
  router.post('/', createController, {
    accepts: [
      'UserCreate',
      {
        schema: 'UserCreateAdmin',
        handler: request => !!request.user?.admin,
        description: 'If user is admin'
      }
    ]
  })
})

Returned data filtering

With returns route configuration parameter, you can automatically filter data returned by your controller according to an OpenAPI Schema, accordingly to the returned HTTP code.

Example

import { collection } from 'http-doc'
import UserGetFilter from '../UserGetFilter.json'

controller('Users', router => {
  router.get('/', listController, {
    returns: {
      200: { schema: 'UserLite', description: 'User data' },
      403: { schema: 'Error', description: 'Not authorized' },
      500: { schema: 'Error', description: 'Unknown error' }
    }
  })
  router.get('/:id', listController, {
    returns: {
      200: { schema: 'User', description: 'User data' },
      403: { schema: 'Error', description: 'Not authorized' },
      500: { schema: 'Error', description: 'Unknown error' }
    }
  })
  router.post('/', createController, {
    returns: {
      201: { schema: 'User', description: 'User data' },
      400: { schema: 'Error', description: 'Bad input data' },
      403: { schema: 'Error', description: 'Not authorized' },
      500: { schema: 'Error', description: 'Unknown error' }
    }
  })
})

Decorators

Decorators are provided to configure your routes, directly from the controllers :

import {
  title,
  description,
  access,
  accepts,
  returns,
  parameter
} from 'http-doc'

export default class UsersController {
  @title('Login')
  @description('Logs in a user')
  @access(true)
  @accepts('Login')
  @parameter('source', 'Source', 'Accepted auth source')
  @returns(200, 'UserJwt', 'Authorized JWT token')
  @returns(403, 'Error', 'Invalid credentials')
  @returns(500, 'Error', 'System error')
  static async login (request, reply, routeConf) {
    // Handling login
    return { loggedIn: true }
  }
}

You need to add babel configuration to handle ES6 decorators (experimental for now):

{
  "plugins": [["@babel/plugin-proposal-decorators", { "version": "2022-03" }]]
}

Authors

• @guillaume-gagnaire