Yet another hapi plugin providing swagger compliant API specifications (swagger specs 2.0) based on routes and joi schemas to be used with swagger-ui.
Supports hapi 17.x and up
For earlier versions check hapi-swaggered 2.x (current default/latest npm install hapi-swaggered --save)
npm install hapi-swaggered@next --savekrakenjs/swaggerize-hapi follows a design driven approach (swagger-schema first) for building APIs. In other words: it supports you to implement an api behind a specific swagger-schema while you have to create and maintain the swagger-schema yourself (or a third-party). In contrast with hapi-swaggered you will have to design your api through hapi route defintions and joi schemas (or did already) and hapi-swaggered will generate it's swagger specifications up on that (Of course not as beautiful and shiny structured as done by hand). Based on this you are able to get beautiful hands-on swagger-ui documentation (like this) for your api up and running (e.g. through hapi-swaggered-ui).
This plugin does not include the swagger-ui interface. It just serves a bare swagger 2.0 compliant json feed. If you are looking for an easy swagger-ui plugin to drop-in? You should have a look at:
requiredTags: an array of strings, only routes with all of the specified tags will be exposed, defaults to:['api']produces: an array of mime type strings, defaults to:[ 'application/json' ]consumes: an array of mime type strings, defaults to:[ 'application/json' ]endpoint: route path to the swagger specification, defaults to:'/swagger'routeTags: an array of strings, all routes exposed by hapi-swaggered will be tagged as specified, defaults to['swagger']stripPrefix: a path prefix which should be stripped from the swagger specifications. E.g. your root resource are located under/api/v12345678/resourceyou might want to strip/api/v12345678, defaults to nullbasePath: string, optional url base path (e.g. used to fix reverse proxy routes)supportedMethods: array of http methods, only routes with mentioned methods will be exposed, in case of a wildcard * a route will be generated for each method, defaults to['get', 'put', 'post', 'delete', 'patch']host: string, overwrite requests host (e.g. domain.tld:1337)schemes: array of allowed schemes e.g.['http', 'https', 'ws', 'wss'](optional)info: exposed swagger api informations, defaults to null (optional)title: string (required)description: string (required)termsOfService: stringcontact: object (optional)name: stringurl: stringemail: string
license: object (optional)name: string: stringurl: string: string
version: version string of your api, which will be exposed (required)
tagging: Options used for grouping routesmode: string, can bepath(routes will be grouped by its path) ortags(routes will be grouped by its tags), default ispathpathLevelinteger, in case of modepathit defines on which level the path grouping will take place (default is 1)stripRequiredTagsboolean, in case of modetagsit defines if therequiredTagswill not be exposed (default is true)
tags: object (or array with objects according to the swagger specs) for defining tag / group descriptions. E.g. you two endpoints/get/thisand/get/thatand the tagging mode is set to path (with pathLevel: 1) they will be groupped unter /get and you are able to define a description through this object as{ 'get': 'get this and that' }, defaults to nullcors: boolean or object with cors configuration as according to the hapijs documentation (defaults to false)cache: caching options for the swagger schema generation as specified inserver.method()of hapi, defaults to:{ expiresIn: 15 * 60 * 1000 }responseValidation: boolean, turn response validation on and off for hapi-swaggered routes, defaults to falseauth: authentication configuration hapijs documentation (default to undefined)securityDefinitions: security definitions according to [swagger specs](https://github.com/swagger-api/swagger-spec/blob/master/versions/2.0.md]
Example configuration for hapi-swaggered + hapi-swaggered-ui
const Hapi = require('hapi');
(async () => {
const server = await new Hapi.Server({
port: 8000
})
await server.register([
require('inert'),
require('vision'),
{
plugin: require('hapi-swaggered'),
options: {
tags: {
'foobar/test': 'Example foobar description'
},
info: {
title: 'Example API',
description: 'Powered by node, hapi, joi, hapi-swaggered, hapi-swaggered-ui and swagger-ui',
version: '1.0'
}
}
},
{
plugin: require('hapi-swaggered-ui'),
options: {
title: 'Example API',
path: '/docs',
authorization: {
field: 'apiKey',
scope: 'query', // header works as well
// valuePrefix: 'bearer '// prefix incase
defaultValue: 'demoKey',
placeholder: 'Enter your apiKey here'
},
swaggerOptions: {
validatorUrl: null
}
}
}
])
server.route({
path: '/',
method: 'GET',
handler (request, h) {
return h.response().redirect('/docs')
}
})
try {
await server.start()
console.log('Server running at:', server.info.uri)
} catch (err) {
console.log(err)
}
})()Demo Routes
server.route({
path: '/foobar/test',
method: 'GET',
options: {
tags: ['api'],
description: 'My route description',
notes: 'My route notes',
handler () {
return {};
}
}
});
server.route({
path: '/foobar/{foo}/{bar}',
method: 'GET',
options: {
tags: ['api'],
validate: {
params: {
foo: Joi.string().required().description('test'),
bar: Joi.string().required()
}
},
handler () {
return {};
}
}
});To assign custom names to your Models use the Joi.meta() option (in previous joi versions Joi.options() may be used)
Joi.object({}).meta({ className: 'FooBar' });To assign a description to your Models use the Joi.meta() option like above
Joi.object({}).meta({ description: 'A description of FooBar' });To override the type a Joi model should be interpreted as, use the Joi.meta() option like above. This is especially useful when utilizing the extend and coerce features of Joi schema definition
Joi.object({}).meta({ swaggerType: string });There are 2 and a half different ways of documenting responses of routes:
The hapi way:
{
options: {
response: {
schema: Joi.object({
bar: Joi.string().description('test').required()
}).description('test'),
status: {
500: Joi.object({
bar: Joi.string().description('test').required()
})
}
}
}
}The plugin way without schemas:
{
options: {
plugins: {
'hapi-swaggered': {
responses: {
default: {description: 'Bad Request'},
500: {description: 'Internal Server Error'}
}
}
},
response: {
schema: Joi.object({
bar: Joi.string().required()
}).description('test')
}
}
}The plugin way with schemas:
{
options: {
plugins: {
'hapi-swaggered': {
responses: {
default: {
description: 'Bad Request', schema: Joi.object({
bar: Joi.string().description('test').required()
})
},
500: {description: 'Internal Server Error'}
}
}
}
}
}Specify an operationId for a route:
{
options: {
plugins: {
'hapi-swaggered': {
operationId: 'testRoute'
}
}
}
}Specify an security options to a route / operation:
{
options: {
plugins: {
'hapi-swaggered': {
security: {}
}
}
}
}Routes can be filtered for tags through the tags query parameter beside the requiredTags property which is always required to be present.
For example:
?tags=public,beta (equal to ?tags=+public,+beta)- will only show apis and routes with tag public AND/OR beta.
?tags=public,-beta (equal to ?tags=+public,-beta)- will only show apis and routes with tag public AND NOT beta.
The routes response schemas which hapi-swaggered is parsing will be dropped by hapi whenever the response validation is disabled. In this case hapi-swaggered will not be able to show any response types. A very low sampling rate is sufficient to keep the repsonse types.
React
Typescript
Django
Laravel
Facebook
Microsoft
Google
Alibaba
D3
Tencent