Hapi OpenAPI 3

Generates OpenAPI 3 for Hapi. Validator should be Joi. Inspired by hapi-swagger.

Installation

npm install hapi-openapi3

Basic setup

const hapiOpenApi3 = require("hapi-openapi3");
const Hapi = require("hapi");
const Joi = require("joi");

const start = async () => {
  const server = Hapi.Server({
    host: "localhost",
    port: 3000,
  });

  await server.register({
    plugin: hapiOpenApi3,
    options: {
      info: {
        title: "Test API Documentation",
        version: "1.0.0",
      },
    },
  });

  server.route({
    path: "/example",
    method: "get",
    options: {
      validate: {
        headers: {
          authorization: Joi.string().required(),
        },
      },
    },
  });

  await server.start();
};

start();

Then open /openapi.json

Options

Server Plugin Options

• includeFn - function that determines if route will be included in open api definition (type: (route: RequestRoute) => boolean, required: true)
• pathFn - function that provides path and must return a new path (type: (path: string) => string))
• jsonPath - path to open api 3 json definition. (type: string, default: /openapi.json)
• pathPrefixSize - selects what segment of the URL path is used to group endpoints. (type: number, default: 1)
• singleSchemaInParams - ignores parameters (header, params, query) that cannot be parsed to a single schema. (type: boolean, default: false)
• info - info about the project (type: info)
• serversFn - function that provides url and must return array of server URL (type: (url: string) => server[])
• servers - array of server URL, this will automatically be derived from hapi's server object if left blank. Ignored if serversFn is provided (type: server[])

Route Options

See examples

• options.validate - used by this plugin to define headers, params, query and payload schema (type: Hapi.RouteOptionsValidate)
• options.response.schema - Schema of response, status code defaults to 200 (type: Joi.Schema)
• options.response.status - schema of response per status code (type: object<string, Joi.schema>)
• options.plugins["hapi-openapi3"].request - You can add examples here. (type: requestOptions)
• options.plugins["hapi-openapi3"].response.schema - You can add examples here. You can also add your schema here (type: responseOptions)
• options.plugins["hapi-openapi3"].response.status - You can add examples here per status code. You can also add your schema here (type: object<string, responseOptions>)

References:

info:

field	description	type	default	required
title	Project Title	string	Documentation Page	true
version	Project Version	string	1.0.0	true
description	Project Description	string		false
termsOfService	Project Terms of Service	string		false
termsOfService	Project Terms of Service	string		false
contact.name	Contact Name	string		false
contact.url	Contact URL	string		false
contact.email	Contact Email	string		false
license.email	License Name	string		false
license.url	License URL	string		false

server:

field	description	type	default	required
url	Server URL	string	<server_url>	true
description	Project Version	string		false

requestOptions:

option	description	type	default	required
example	Single Example	any		false
examples	Multiple Examples	object<string, any>		false

responseOptions:

option	description	type	default	required
header	Joi Schema of Header	string		false
payload	Joi Schema of Payload	string		false
example	Single Example	any		false
examples	Multiple Examples	object<string, any>		false