This is a OpenAPI (aka Swagger) plug-in for Hapi When installed it will self document the API interface in a project.
| Version | Hapi | Joi | Node | Release Notes |
|---|---|---|---|---|
v12.x | >=19.0.0 @hapi/hapi | >=17.0.0 | >=12 | #644 |
v11.x | >=18.4.0 @hapi/hapi | >=16.0.0 | >=8 | #631 |
v10.x | >=18.3.1 @hapi/hapi | >=14.0.0 | >=8 | #587 |
9.x | >=17 hapi | <14.0.0 | >=8 | #487 |
7.x | <17 hapi | ??? | ??? | #325 |
You can add the module to your Hapi using npm:
> npm install hapi-swagger --saveIf 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 @hapi/inert --save
> npm install @hapi/vision --saveIn 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.
constHapi=require('@hapi/hapi');constInert=require('@hapi/inert');constVision=require('@hapi/vision');constHapiSwagger=require('hapi-swagger');constPack=require('./package');(async()=>{constserver=awaitnewHapi.Server({host: 'localhost',port: 3000,});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 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 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 be http://localhost:3000/documentation.
hapi-swagger exports its own typescript definition file that can be used when registering the plugin with Hapi. See example below:
npm i @types/hapi__hapi @types/hapi__inert @types/hapi__joi @types/hapi__vision @types/node hapi-swagger --save-devimport*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 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.