Beautiful API documentation generator for Hapi using Vue
npm install @surveylegend/hapi-docs
- Introduction
- Features
- Installation
- Usage
- Demo
- Documentation
- Plugin Options
- Route Options
- Tagging API Routes
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®.
- 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.
> This package can be used in hapi v19 or higher.
You can install the package via yarn:
``bash`
$ yarn add @surveylegend/hapi-docs
> Note
> Inert is a required dependency for hapi-docs to work properly.
`javascript
import Hapi from '@hapi/hapi'
import Inert from '@hapi/inert'
import Joi from 'joi'
import HapiDocs from '@surveylegend/hapi-docs'
import { version } from './package'
const options = {
info: {
title: 'Test API Reference',
version
}
}
const startServer = async () => {
const server = Hapi.server({
host: 'localhost',
port: 3000
})
await server.register([
{
plugin: Inert
},
{
plugin: HapiDocs,
options
}
])
await server.start()
console.log(Server listening on ${server.info.uri})
}
startServer().catch(console.error)
`
You can see a live demo version of hapi-docs. Check it out at hapi-docs
- endpoint: (string) The path of the documentation - default: /docs
- : (string) The base path before the API, i.e. /v2 - default: /
- : (string) The absolute path to the template folder, i.e. /template
- : (string) The hostname or IP serving the API, i.e. localhost:3000
- : (string) The transfer protocol of the API, i.e. http, https
- : (number) The segment of the URL path that is used to group endpoints - default: 1
- : (string) The sort method for groups, i.e. name, ordered - default: name
- : (string) The sort method for endpoints, i.e. path, method, ordered - default: path
-
- : (string) The title of the documentation - default: API Reference
- : (string) The version number of the API - default: 0.0.1
- : (array) The description of the API.tags
- : (array) Contains tag objectsname
- : (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
- : (boolean) Whether a group is internal - default: false
- : (boolean) Whether a group name is uppercase - default: false
- :descriptions
- : (array) The description of the errors.codes
- : (array) Contains error code objectsstatus
- : (string) The status of the error code, i.e. 418 - I'm A Teapot
- : (string) The description of the error code.auth
- : (boolean, string or object) The security strategy used for plugin resources - default: false
- order: (int) The order which endpoints are sorted by.deprecated
- : (boolean) Whether an endpoint is deprecated - default: false
- : (boolean) Whether an endpoint is internal - default: false
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:
`javascript``
{
method: 'GET',
path: '/route',
options: {
handler: [...],
[...]
tags: ['api']
}
}
Please see CONTRIBUTING for details.
If you discover any security-related issues, please email henrik@surveylegend.com instead of using the issue tracker.
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®.
The MIT License (MIT). Please see License File for more information.