hapi docs

Beautiful API documentation generator for Hapi using Vue

Vue

Introduction
Features
Installation
Usage
Demo
Documentation

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:

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.