hapi-swagger

hapi-swagger

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

Review release notes for v7.0.0

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

• Options Reference
• Usage Guide

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');

const server = new Hapi.Server();
server.connection({
        host: 'localhost',
        port: 3000
    });

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

server.register([
    Inert,
    Vision,
    {
        'register': HapiSwagger,
        'options': options
    }], (err) => {
        server.start( (err) => {
           if (err) {
                console.log(err);
            } else {
                console.log('Server running at:', server.info.uri);
            }
        });
    });

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}/',
    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()
                        .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.

Lab test

The project has integration and unit tests. To run the test within the project type one of the following commands. or

$ npm test

or

$ lab
$ lab -r html -o coverage.html
$ lab -r html -o coverage.html --lint
$ lab -r console -o stdout -r html -o coverage.html --lint

If you are considering sending a pull request please add tests for the functionality you add or change.

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.

Issues

If you find any issue please file here on github and I will try and fix them.