hapi-swaggered 3.x

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)

Install

1npm install hapi-swaggered@next --save

Similar swagger-projects for hapi

krakenjs/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).

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

• hapi-swaggered-ui

Plugin Configuration

• 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/resource you might want to strip /api/v12345678, defaults to null
• basePath: 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: string
  • contact: object (optional)
    • name: string
    • url: string
    • email: string
  • license: object (optional)
    • name: string: string
    • url: string: string
  • version: version string of your api, which will be exposed (required)
• tagging: Options used for grouping routes
  • mode: string, can be path (routes will be grouped by its path) or tags (routes will be grouped by its tags), default is path
  • pathLevel integer, in case of mode path it defines on which level the path grouping will take place (default is 1)
  • stripRequiredTags boolean, in case of mode tags it defines if the requiredTags will 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/this and /get/that and 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 null
• cors: 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 in server.method() of hapi, defaults to: { expiresIn: 15 * 60 * 1000 }
• responseValidation: boolean, turn response validation on and off for hapi-swaggered routes, defaults to false
• auth: 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

Example configuration for hapi-swaggered + hapi-swaggered-ui

1const Hapi = require('hapi');
2
3(async () => {
4  const server = await new Hapi.Server({
5    port: 8000
6  })
7
8  await server.register([
9    require('inert'),
10    require('vision'),
11    {
12      plugin: require('hapi-swaggered'),
13      options: {
14        tags: {
15          'foobar/test': 'Example foobar description'
16        },
17        info: {
18          title: 'Example API',
19          description: 'Powered by node, hapi, joi, hapi-swaggered, hapi-swaggered-ui and swagger-ui',
20          version: '1.0'
21        }
22      }
23    },
24    {
25      plugin: require('hapi-swaggered-ui'),
26      options: {
27        title: 'Example API',
28        path: '/docs',
29        authorization: {
30          field: 'apiKey',
31          scope: 'query', // header works as well
32          // valuePrefix: 'bearer '// prefix incase
33          defaultValue: 'demoKey',
34          placeholder: 'Enter your apiKey here'
35        },
36        swaggerOptions: {
37          validatorUrl: null
38        }
39      }
40    }
41  ])
42
43  server.route({
44    path: '/',
45    method: 'GET',
46    handler (request, h) {
47      return h.response().redirect('/docs')
48    }
49  })
50
51  try {
52    await server.start()
53    console.log('Server running at:', server.info.uri)
54  } catch (err) {
55    console.log(err)
56  }
57})()

Demo Routes

1server.route({
2  path: '/foobar/test',
3  method: 'GET',
4  options: {
5    tags: ['api'],
6    description: 'My route description',
7    notes: 'My route notes',
8    handler () {
9      return {};
10    }
11  }
12});
13
14server.route({
15  path: '/foobar/{foo}/{bar}',
16  method: 'GET',
17  options: {
18    tags: ['api'],
19    validate: {
20      params: {
21        foo: Joi.string().required().description('test'),
22        bar: Joi.string().required()
23      }
24    },
25    handler () {
26      return {};
27    }
28  }
29});

Features

Model naming

To assign custom names to your Models use the Joi.meta() option (in previous joi versions Joi.options() may be used)

1Joi.object({}).meta({ className: 'FooBar' });

Model description

To assign a description to your Models use the Joi.meta() option like above

1Joi.object({}).meta({ description: 'A description of FooBar' });

Type naming

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

1Joi.object({}).meta({ swaggerType: string });

Document responses

There are 2 and a half different ways of documenting responses of routes:

The hapi way:

1{
2  options: {
3    response: {
4      schema: Joi.object({
5        bar: Joi.string().description('test').required()
6      }).description('test'),
7      status: {
8        500: Joi.object({
9          bar: Joi.string().description('test').required()
10        })
11      }
12    }
13  }
14}

The plugin way without schemas:

1{
2  options: {
3    plugins: {
4      'hapi-swaggered': {
5        responses: {
6          default: {description: 'Bad Request'},
7          500: {description: 'Internal Server Error'}
8        }
9      }
10    },
11    response: {
12      schema: Joi.object({
13        bar: Joi.string().required()
14      }).description('test')
15    }
16  }
17}

The plugin way with schemas:

1{
2  options: {
3    plugins: {
4      'hapi-swaggered': {
5        responses: {
6          default: {
7            description: 'Bad Request', schema: Joi.object({
8              bar: Joi.string().description('test').required()
9            })
10          },
11          500: {description: 'Internal Server Error'}
12        }
13      }
14    }
15  }
16}

Specify an operationId for a route:

1{
2  options: {
3    plugins: {
4      'hapi-swaggered': {
5        operationId: 'testRoute'
6      }
7    }
8  }
9}

Specify an security options to a route / operation:

1{
2  options: {
3    plugins: {
4      'hapi-swaggered': {
5        security: {}
6      }
7    }
8  }
9}

Tag filtering

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.

Known issues

No response types

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.