exos-hapi-docs

• Introduction
• Features
• Usage
• Documentation
  • Plugin Options
  • Route Options
  • Tagging API Routes

Introduction

exos-hapi-docs is a API Documentation Generator for NodeJS proyects with HAPI Framework.

Features

• Intuitive design — The description of your API resides on the left part of the documentation, while all of the code examples reside on the right. Of course the layout is fully responsive and flawlessly adapts to tablets and phones.

• Single page — The whole documentation resides on a single page, without sacrificing linkability. As you scroll through the documentation, your browser’s hash will update to the nearest section, which means linking to a particular point in the documentation remains natural and easy.

• Scroll spy — Thanks to our custom and optimized scroll spy script, the far left navigation will smartly display your current position in the documentation, while scrolling through the documentation. It's swift and remains excellent even for larger documents.

• Dark theme — Seamless switching between light and dark theme using a toggle. Supports prefers-color-scheme media query for automatic switching as well.

• Markdown support — Use Markdown to describe your API. Markdown makes it easy to articulate your documentation.

• Code examples in multiple languages — Configurable support for multiple languages. Easily choose which language to currently display in your documentation by switching between tabs.

• Syntax highlighting — Supports over 100 languages out of the box.

• RTL Support — Full Right-to-Left support for languages such as Arabic, Persian (Farsi), Hebrew, etc.

• Anchor tags — With one click, users can easily link to a parameter, thanks to auto generated anchor tags.

Usage

Note Inert is a required dependency for hapi-docs to work properly.

const Hapi = require('@hapi/hapi')
const Inert = require('@hapi/inert')
const Joi = require('joi')
const HapiDocs = require('../lib')
const { version } = require('./package')

async function startServer() {
    const server = Hapi.server({
        host: 'localhost',
        port: 3000
    })
    
    const { version } = JSON.parse((await readFile('./package.json')).toString())

    await server.register([
        {
            plugin: Inert
        },
        {
            plugin: HapiDocs,
            options: {
                info: {
                    title: 'Test API Reference',
                    version
                }
            }
        }
    ])

    await server.start()

    console.log(`Server listening on ${server.info.uri}`)
}

startServer().catch(console.error)

Documentation

Plugin Options

• endpoint: (string) The path of the documentation - default: /docs
• basePath: (string) The base path before the API, i.e. /v2 - default: /
• templatePath: (string) The absolute path to the template folder, i.e. /template
• host: (string) The hostname or IP serving the API, i.e. localhost:3000
• scheme: (string) The transfer protocol of the API, i.e. http, https
• pathPrefixSize: (number) The segment of the URL path that is used to group endpoints - default: 1
• sortTags: (string) The sort method for groups, i.e. name, ordered - default: name
• sortEndpoints: (string) The sort method for endpoints, i.e. path, method, ordered - default: path
• info
  • title: (string) The title of the documentation - default: API Reference
  • version: (string) The version number of the API - default: 0.0.1
  • descriptions: (array) The description of the API.
• tags: (array) Contains tag objects
  • name: (string) The name of the group.
  • descriptions: (array) The description of the group.
  • order: (int) The order which groups are sorted by.
  • deprecated: (boolean) Whether a group is deprecated - default: false
  • internal: (boolean) Whether a group is internal - default: false
  • uppercase: (boolean) Whether a group name is uppercase - default: false
• errors:
  • descriptions: (array) The description of the errors.
  • codes: (array) Contains error code objects
    • status: (string) The status of the error code, i.e. 418 - I'm A Teapot
    • description: (string) The description of the error code.
• auth: (boolean, string or object) The security strategy used for plugin resources - default: false

Route Options

• order: (int) The order which endpoints are sorted by.
• deprecated: (boolean) Whether an endpoint is deprecated - default: false
• internal: (boolean) Whether an endpoint is internal - default: false

Tagging API Routes

If you want a route to appear in the documentation, you have to set tags: [api] for this specific route.

Here is an example snippet of a route option:

{
  method: 'GET',
  path: '/route',
  options: {
    handler: [...],
    [...]
    tags: ['api']
  }
}