brave/hapi-swagger

Name: hapi-swagger

Owner: Brave Software

Description: A Swagger interface for HAPI

Forked from: glennjones/hapi-swagger

Created: 2016-10-13 01:24:26.0

Updated: 2017-01-04 18:39:34.0

Pushed: 2017-09-26 03:04:31.0

Homepage: null

Size: 5062

Language: JavaScript

GitHub Committers

User	Most Recent Commit	# Commits

Other Committers

User	Email	Most Recent Commit	# Commits

README

hapi-swagger

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

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.

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

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

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

er.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);
        }
    });
});

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

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.