hapi-swagger

This is a OpenAPI (aka Swagger) plug-in for Hapi When installed it will self document the API interface in a project.

Compatibility

Version	Hapi	Joi	Node	Release Notes
17.x	>=20.0.0 @hapi/hapi	>=17.0.0 joi	>=16	Release
16.x	>=20.0.0 @hapi/hapi	>=17.0.0 joi	>=14	#795
15.x	>=20.0.0 @hapi/hapi	>=17.0.0 joi	>=14	#782
14.x	>=19.0.0 @hapi/hapi	>=17.0.0 joi	>=12	#680
13.x	>=19.0.0 @hapi/hapi	>=17.0.0 @hapi/joi	>=12	#660
12.x	>=19.0.0 @hapi/hapi	>=17.0.0 @hapi/joi	>=12	#644
11.x	>=18.4.0 @hapi/hapi	>=16.0.0 @hapi/joi	>=8	#631
10.x	>=18.3.1 @hapi/hapi	>=14.0.0 @hapi/joi	>=8	#587
9.x	>=17 hapi	<14.0.0	>=8	#487
7.x	<17 hapi	???	???	#325

Installation

You can add the module to your Hapi using npm:

1> npm install hapi-swagger --save

hapi-swagger no longer bundles joi to fix #648. Install hapi-swagger with peer dependencies using:

1npx install-peerdeps hapi-swagger

If you want to view the documentation from your API you will also need to install the inert and vision plugs-ins which support templates and static content serving.

1> npm install @hapi/inert --save
2> npm install @hapi/vision --save

Documentation

• Options Reference
• Usage Guide

Quick start

In your Hapi apps please check the main JavaScript file and add the following code to already created a Hapi server object. You will also add the routes for you API as describe on hapi website.

1const Hapi = require('@hapi/hapi');
2const Inert = require('@hapi/inert');
3const Vision = require('@hapi/vision');
4const HapiSwagger = require('hapi-swagger');
5const Pack = require('./package');
6
7(async () => {
8    const server = Hapi.server({
9        port: 3000,
10        host: 'localhost'
11    });
12
13    const swaggerOptions = {
14        info: {
15                title: 'Test API Documentation',
16                version: Pack.version,
17            },
18        };
19
20    await server.register([
21        Inert,
22        Vision,
23        {
24            plugin: HapiSwagger,
25            options: swaggerOptions
26        }
27    ]);
28
29    try {
30        await server.start();
31        console.log('Server running at:', server.info.uri);
32    } catch(err) {
33        console.log(err);
34    }
35
36    server.route(Routes);
37})();

Tagging your API routes

As a project may be a mixture of web pages and API endpoints you need to tag the routes you wish Swagger to document. Simply add the tags: ['api'] property to the route object for any endpoint you want documenting.

You can even specify more tags and then later generate tag-specific documentation. If you specify tags: ['api', 'foo'], you can later use /documentation?tags=foo to load the documentation on the HTML page (see next section).

1{
2    method: 'GET',
3    path: '/todo/{id}/',
4    options: {
5        handler: handlers.getToDo,
6        description: 'Get todo',
7        notes: 'Returns a todo item by the id passed in the path',
8        tags: ['api'], // ADD THIS TAG
9        validate: {
10            params: Joi.object({
11                id : Joi.number()
12                        .required()
13                        .description('the id for the todo item'),
14            })
15        }
16    },
17}

Once you have tagged your routes start the application. The plugin adds a page into your site with the route /documentation, so the the full URL for the above options would be http://localhost:3000/documentation.

Typescript

hapi-swagger exports its own typescript definition file that can be used when registering the plugin with Hapi. See example below:

Install Typescript Definition Files

1npm i @types/hapi__hapi @types/hapi__inert @types/hapi__joi @types/hapi__vision @types/node hapi-swagger --save-dev

Register Plugin with Typescript

1import * as Hapi from '@hapi/hapi';
2import * as HapiSwagger from 'hapi-swagger';
3
4// code omitted for brevity
5
6const swaggerOptions: HapiSwagger.RegisterOptions = {
7    info: {
8        title: 'Test API Documentation'
9    }
10};
11
12const plugins: Array<Hapi.ServerRegisterPluginObject<any>> = [
13    {
14        plugin: Inert
15    },
16    {
17        plugin: Vision
18    },
19    {
20        plugin: HapiSwagger,
21        options: swaggerOptions
22    }
23];
24
25await server.register(plugins);

Contributing

Read the contributing guidelines for details.

Thanks

I would like to thank all that have contributed to the project over the last couple of years. This is a hard project to maintain, getting Hapi to work with Swagger is like putting a round plug in a square hole. Without the help of others it would not be possible.