Skip to content

hapi-swagger/hapi-swagger

Folders and files

NameName
Last commit message
Last commit date

Latest commit

ea3d000 · Dec 10, 2024
Dec 1, 2024
Jun 18, 2023
Nov 4, 2023
Sep 21, 2023
Dec 9, 2024
Jun 10, 2023
Jun 12, 2023
Dec 1, 2024
May 11, 2019
Nov 26, 2017
Feb 12, 2022
Jun 18, 2023
Jun 18, 2023
Jan 24, 2020
Jun 19, 2023
Sep 21, 2023
Dec 5, 2015
May 25, 2019
Mar 13, 2019
Sep 21, 2023
Dec 10, 2024
Aug 11, 2024
Aug 31, 2023

Repository files navigation

hapi-swagger

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

Maintainers Wanted GitHub Workflow Status npm downloads MIT license

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:

> npm install hapi-swagger --save

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

npx 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.

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

Documentation

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.

const Hapi = require('@hapi/hapi');
const Inert = require('@hapi/inert');
const Vision = require('@hapi/vision');
const HapiSwagger = require('hapi-swagger');
const Pack = require('./package');

(async () => {
    const server = Hapi.server({
        port: 3000,
        host: 'localhost'
    });

    const swaggerOptions = {
        info: {
                title: 'Test API Documentation',
                version: Pack.version,
            },
        };

    await server.register([
        Inert,
        Vision,
        {
            plugin: HapiSwagger,
            options: swaggerOptions
        }
    ]);

    try {
        await server.start();
        console.log('Server running at:', server.info.uri);
    } catch(err) {
        console.log(err);
    }

    server.route(Routes);
})();

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

{
    method: 'GET',
    path: '/todo/{id}/',
    options: {
        handler: handlers.getToDo,
        description: 'Get todo',
        notes: 'Returns a todo item by the id passed in the path',
        tags: ['api'], // ADD THIS TAG
        validate: {
            params: Joi.object({
                id : Joi.number()
                        .required()
                        .description('the id for the todo item'),
            })
        }
    },
}

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

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

Register Plugin with Typescript

import * as Hapi from '@hapi/hapi';
import * as HapiSwagger from 'hapi-swagger';

// code omitted for brevity

const swaggerOptions: HapiSwagger.RegisterOptions = {
    info: {
        title: 'Test API Documentation'
    }
};

const plugins: Array<Hapi.ServerRegisterPluginObject<any>> = [
    {
        plugin: Inert
    },
    {
        plugin: Vision
    },
    {
        plugin: HapiSwagger,
        options: swaggerOptions
    }
];

await 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.