Repository files navigation

This is aOpenAPI (aka Swagger) plug-in forHapi When installed it will self document the API interfacein a project.

You can add the module to your Hapi using npm:

> npm install hapi-swagger --save

hapi-swagger no longer bundlesjoi to fix#648. Installhapi-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 theinert andvision plugs-ins which support templates and staticcontent serving.

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

• Options Reference
• Usage Guide

In your Hapi apps please check the main JavaScript file and add the following code to already created a Hapiserver object.You will also add the routes for you API as describe onhapi website.

constHapi=require('@hapi/hapi');constInert=require('@hapi/inert');constVision=require('@hapi/vision');constHapiSwagger=require('hapi-swagger');constPack=require('./package');(async()=>{constserver=Hapi.server({port:3000,host:'localhost'});constswaggerOptions={info:{title:'Test API Documentation',version:Pack.version,},};awaitserver.register([Inert,Vision,{plugin:HapiSwagger,options:swaggerOptions}]);try{awaitserver.start();console.log('Server running at:',server.info.uri);}catch(err){console.log(err);}server.route(Routes);})();

As a project may be a mixture of web pages and API endpoints you need to tag the routes you wish Swagger todocument. Simply add thetags: ['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 specifytags: ['api', 'foo'], you can later use/documentation?tags=foo to load the documentation on theHTML 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 TAGvalidate:{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 behttp://localhost:3000/documentation.

hapi-swagger exports its own typescript definition file that can be used when registering the plugin withHapi. See example below:

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

import*asHapifrom'@hapi/hapi';import*asHapiSwaggerfrom'hapi-swagger';// code omitted for brevityconstswaggerOptions:HapiSwagger.RegisterOptions={info:{title:'Test API Documentation'}};constplugins:Array<Hapi.ServerRegisterPluginObject<any>>=[{plugin:Inert},{plugin:Vision},{plugin:HapiSwagger,options:swaggerOptions}];awaitserver.register(plugins);

Read thecontributing 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.