Skip to content
A Swagger interface for HAPI
Branch: master
Clone or download
Pull request Compare This branch is 11 commits behind glennjones:master.
Fetching latest commit…
Cannot retrieve the latest commit at this time.
Permalink
Type Name Latest commit message Commit time
Failed to load latest commit information.
.github
examples
lib
public
test
.editorconfig
.eslintignore
.eslintrc.json
.gitattributes
.gitignore
.travis.yml
README.md
index.js
jsconfig.json
license.txt
optionsreference.md
package-lock.json
package.json
usageguide.md

README.md

hapi-swagger

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.

Install

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

Documentation

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 hapijs.com 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([
        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: {
                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.

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.

You can’t perform that action at this time.