Share your code. npm Orgs help your team discover, share, and reuse code. Create a free org »



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

    build status Coverage Status npm downloads MIT license

    Release Notes for v9.0.x which only supports hapi v17 and above. Note: For hapi versions below v17, you must use versions v7.x.x of this module.


    You can add the module to your HAPI using npm:

    $ npm install hapi-swagger --save

    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 inert --save
    $ npm install vision --save


    Quick start

    In your HAPI apps main JavaScript file add the following code to created a HAPI server object. You will also add the routes for you API as describe on site.

    const Hapi = require('hapi');
    const Inert = require('inert');
    const Vision = require('vision');
    const HapiSwagger = require('hapi-swagger');
    const Pack = require('./package');
    (async () => {
        const server = await new Hapi.Server({
            host: 'localhost',
            port: 3000,
        const swaggerOptions = {
            info: {
                    title: 'Test API Documentation',
                    version: Pack.version,
        await server.register([
                plugin: HapiSwagger,
                options: swaggerOptions
        try {
            await server.start();
            console.log('Server running at:',;
        } catch(err) {

    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}/',
        config: {
            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: {
                    id : Joi.number()
                            .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.


    Read the contributing guidelines for details.


    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.


    npm i hapi-swagger

    Downloadslast 7 days






    last publish


    • avatar