hapi-openapi3 v1.0.9

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: