hapi-doc v1.0.5

hapi-doc

Create an API documentation endpoint for your hapi application

1. Introduction
2. Installation
3. Usage

Introduction

hapi-doc is a plugin for hapi which generate an API documentation based on hapi's routes settings.

A demo is accessible here!

Installation

Using npm:

$ npm install hapi-doc

Using yarn:

$ yarn add hapi-doc

Usage

Import

Using CommonJS:

const hapidoc = require('hapi-doc')

Using ESM:

import hapidoc from 'hapi-doc'

Create hapi server

Afterwards create your hapi server if not already done:

const hapi = require("@hapi/hapi")

const server = hapi.server({ port: 8080 })

Registration

Finally register the plugin. Available options are described in the next section.

await server.register({ plugin: hapidoc, options })

Options

This is an example of valid options

let options = {
    path: '/path/to/documentation',
    title: 'Documentation Title',
    version: '0.42.0',
    description: 'Description of the API',
    tags: ['pet', 'store', 'user'], 
    servers: [{url: 'http://localhost:8080'}],
}

Configure

hapi-doc will observe server's routes options in order to build the API model. Here are the following routes options that are used.

The schema description for request and response objects must be done using Joi.

Here is an example of hapi route configuration and the corresponding documentation endpoint generated.

server.route({
  method: 'PUT',
  path: '/users/{userId}',
  handler: async (req, h) => {},
  options:{
    tags: ['users'],
    description: 'Update a user',
    validate:{
      params: Joi.object({
        userId: Joi.string()
          .guid({version:'uuidv4'})
          .description('Id of the user')
          .required()
      }), 
      payload: Joi.object({
        email: Joi.string().regex(EMAIL_RGX),
        password: Joi.string(),
        bio: Joi.string()
      })
    },
    response:{
      status:{
        200: Joi.string().description('successful operation'),
        404: Joi.string().description('user not found'),
      }
    }
  }
})