krakenjshapi-openapi
Note: this project was renamed from 'swaggerize-hapi' to 'hapi-openapi'.
hapi-openapi is a design-driven approach to building RESTful services with OpenAPI (Swagger) and Hapi.
hapi-openapi provides the following features:
- API schema validation.
- Routes based on the OpenAPI document.
- API documentation route.
- Input validation.
Why "Design Driven"
There are already a number of modules that help build RESTful APIs for node with OpenAPI. However, these modules tend to focus on building the documentation or specification as a side effect of writing the application business logic.
hapi-openapi begins with the OpenAPI document first. This facilitates writing APIs that are easier to design, review, and test.
At runtime, hapi-openapi uses the API specification to build routes from previously defined paths. This ensures that everything specified is what is implemented.
Quick Start with a Generator
This guide will let you go from an api.json to a service project in no time flat.
First install generator-swaggerize (and yo if you haven't already):
$ npm install -g yo
$ npm install -g generator-swaggerizeNow run the generator.
$ mkdir petstore && cd $_
$ yo swaggerizeFollow the prompts (note: make sure to choose hapi as your framework choice).
You now have a working api and can use something like SwaggerHub to explore it.
Manual Usage
const Hapi = require('@hapi/hapi');
const Path = require("path");
const server = new Hapi.Server( { port: 3000 } );
async function init () {
await server.register({
plugin: require('hapi-openapi'),
options: {
api: Path.join(__dirname, './config/pets.json'),
handlers: Path.join(__dirname, './handlers')
}
});
await server.start();
console.log( server.info.uri );
}
init();Hapi Plugin
The plugin will be registered as openapi on server.plugins with the following exposed:
getApi()- the resolved Swagger document.setHost(host)- a helper function for setting thehostproperty on theapi.
Configuration Options
api- a path to a valid OpenAPI 2.0 document, or a valid document in the form of an object.- deprecated
docspath- the path to expose api docs for swagger-ui, etc. Defaults to/api-docs. docs- an object used to configure the api docs route.path- the path to expose api docs for swagger-ui, etc. Defaults to/api-docs.auth- options auth config for this route.stripExtensions- strip vendor extensions from docs. Defaults to true.prefixBasePath- prefix path of docs with he OpenAPI document'sbasePathvalue. Defaults to true.
handlers- either a string directory structure for route handlers, object, or not set if usingx-hapi-handler.extensions- an array of file extension types to use when scanning for handlers. Defaults to['js'].vhost- optional domain string (see hapi route options).cors- optional cors setting (see hapi route options).outputvalidation- optional validate response data.
Mount Path
Api path values will be prefixed with the OpenAPI document's basePath value. This behavior can be negated if you set the option docs.prefixBasePath to false.
Handlers Directory
The options.handlers option specifies a directory to scan for handlers. These handlers are bound to the api paths defined in the OpenAPI document.
handlers
|--foo
| |--bar.js
|--foo.js
|--baz.jsWill route as:
foo.js => /foo
foo/bar.js => /foo/bar
baz.js => /bazPath Parameters
The file and directory names in the handlers directory can also represent path parameters.
For example, to represent the path /users/{id}:
handlers
|--users
| |--{id}.jsThis works with directory names as well:
handlers
|--users
| |--{id}.js
| |--{id}
| |--foo.jsTo represent /users/{id}/foo.
Handlers File
Each provided javascript file should export an object containing functions with HTTP verbs as keys.
Example:
module.exports = {
get: function (req, h) { ... },
put: function (req, h) { ... },
...
}Optionally, pre handlers can be used by providing an array of handlers for a method:
module.exports = {
get: [
function p1(req, h) { ... },
function handler(req, h) { ... }
],
}Handlers Object
The directory generation will yield this object, but it can be provided directly as options.handlers.
Example:
{
'foo': {
'get': function (req, h) { ... },
'bar': {
'get': function (req, h) { ... },
'post': function (req, h) { ... }
}
}
...
}X-Hapi-Handler
Alternatively the API document can set x-hapi-handler attribute on each defined paths element if handlers is not defined.
Example:
"/pets/{id}": {
"x-hapi-handler": "./routes/pets-by-id.js",
.
.
.This will construct a handlers object from the given x-hapi-handler files.
X-Hapi-Options
There is now support at the operations level for x-hapi-options which represent individual Hapi Route Optijons.
This support is limited to configuration supported by the JSON file type.
Example:
"/internal": {
"post": {
"x-hapi-options": {
"isInternal": true
}
.
.
.Authentication
Support for OpenAPI security schemes requires that relevant authentication scheme and strategy are registered before the hapi-openapi plugin. See the hapi docs for information about authentication schemes and strategies.
The name of the hapi authentication strategy is expected to match the name field of the OpenAPI security requirement object.
Example:
securityDefinitions:
api_key:
type: apiKey
name: Authorization
in: header
paths:
'/users/':
get:
security:
- api_key: []const server = new Hapi.Server();
await server.register({ plugin: AuthTokenScheme });
server.auth.strategy('api_key', 'auth-token-scheme', {
validateFunc: async function (token) {
// Implement validation here, return { credentials, artifacts }.
}
});
await server.register({
plugin: require('hapi-openapi'),
options: {
api: require('./config/pets.json'),
handlers: Path.join(__dirname, './handlers')
}
});X-Hapi-Auth
Alternatively it may be easier to automatically register a plugin to handle registering the necessary schemes and strategies.
x-hapi-auth-schemes
The root document can contain an x-hapi-auth-schemes object specifying different plugins responsible for registering auth schemes.
Example:
"x-hapi-auth-schemes": {
"apiKey": "../lib/xauth-scheme.js"
}This plugin will be passed the following options:
name- the auth scheme name, in this exampleapiKey.
x-hapi-auth-strategy
The securityDefinitions entries can contain an x-hapi-auth-strategy attribute pointing to a plugin responsible for registering auth strategies.
Example:
"securityDefinitions": {
"api_key": {
"x-hapi-auth-strategy": "../lib/xauth-strategy.js",
"type": "apiKey",
"name": "authorization",
"in": "header"
}
}The plugin will be passed the following options:
name- thesecurityDefinitionsentry's key. In this example,api_key. This is typically used as the strategy name.scheme- thesecurityDefinitionstype. In this example,apiKey. This should match ax-hapi-auth-schemename.where-securityDefinitionsentryinattribute. This is search for thelookupvalue; in this exampleheader.lookup-securityDefinitionsentrynameattribute. Used as the name to look up againstwhere.
The way you can make these play together is that for every type, a scheme exists that delegates some lookup or evaluation to the appropriate strategy.
Example:
//xauth-scheme.js
const register = function (server, { name }) {
server.auth.scheme(name /*apiKey*/, (server, /* options received from the strategy */ { validate }) => {
return {
authenticate: async function (request, h) {
return h.authenticated(await validate(request));
}
};
});
};
module.exports = { register, name: 'x-hapi-auth-scheme' };and
//xauth-strategy.js
const Boom = require('@hapi/boom');
const register = function (server, { name, scheme, where, lookup }) {
server.auth.strategy(name, /* the scheme to use this strategy with */ scheme, {
//Define a validate function for the scheme above to receive
validate: async function (request) {
const token = request.headers[lookup];
//Some arbitrary example
if (token === '12345') {
return { credentials: { scope: ['read'] }, artifacts: { token } };
}
throw Boom.unauthorized();
}
});
};
module.exports = { register, name: 'x-hapi-auth-strategy' };