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:

| 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 |

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

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

| 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 |