Generates OpenAPI 3 for Hapi. Validator should be Joi. Inspired by hapi-swagger.
npm install hapi-openapi3
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
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[])
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>)
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 |