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

Introduction

NOTE: Version 3.x of this project is in pure ESM and can not be used in CommonJS projects. If you want to use this project in a CommonJS project, please use v2.x. Version 2 and 3 are at feature parity, it's jst the imports and exports that differ. This is to support those who have not made the switch to ESM yet.

hapi-docs is perhaps the best and most modern API Documentation Generator out there. From your code blocks to description texts, you simply type everything in Markdown. Then all you need to do is to enjoy a blazing fast single-page responsive documentation, which smartly supports linkability, Syntax highlighting, RTL languages, and perfectionist eyes. hapi-docs is an open-source library brought to you by SurveyLegend®.

Features

• Intuitive design — Inspired by Stripe’s API docs. 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.

Installation

This package can be used in hapi v19 or higher.

You can install the package via yarn:

$ yarn add @surveylegend/hapi-docs

Usage

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

import { readFile } from 'node:fs/promises'
import Hapi from '@hapi/hapi'
import Inert from '@hapi/inert'
import Joi from 'joi'
import HapiDocs from '@surveylegend/hapi-docs'

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)

Demo

You can see a live demo version of hapi-docs. Check it out at hapi-docs

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']
  }
}

Contributing

Please see CONTRIBUTING for details.

Security

If you discover any security-related issues, please email [email protected] instead of using the issue tracker.

Credits

Developed and designed by:

• Henrik Ruscon
• Robert Michalski

hapi-docs is inspired by hapi-swagger, lout, and Stripe’s API docs; and fully sponsored by SurveyLegend®.

License

The MIT License (MIT). Please see License File for more information.