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 |
|---|---|---|---|---|
17.x |
>=20.0.0 @hapi/hapi |
>=17.0.0 joi |
>=16 |
Release |
16.x |
>=20.0.0 @hapi/hapi |
>=17.0.0 joi |
>=14 |
#795 |
15.x |
>=20.0.0 @hapi/hapi |
>=17.0.0 joi |
>=14 |
#782 |
14.x |
>=19.0.0 @hapi/hapi |
>=17.0.0 joi |
>=12 |
#680 |
13.x |
>=19.0.0 @hapi/hapi |
>=17.0.0 @hapi/joi |
>=12 |
#660 |
12.x |
>=19.0.0 @hapi/hapi |
>=17.0.0 @hapi/joi |
>=12 |
#644 |
11.x |
>=18.4.0 @hapi/hapi |
>=16.0.0 @hapi/joi |
>=8 |
#631 |
10.x |
>=18.3.1 @hapi/hapi |
>=14.0.0 @hapi/joi |
>=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 --savehapi-swagger no longer bundles joi to fix #648. Install hapi-swagger with peer dependencies using:
npx install-peerdeps hapi-swaggerIf 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 please check the main JavaScript file and add the following code to already created a Hapi server object.
You will also add the routes for you API as describe on hapi website.
const Hapi = require('@hapi/hapi');
const Inert = require('@hapi/inert');
const Vision = require('@hapi/vision');
const HapiSwagger = require('hapi-swagger');
const Pack = require('./package');
(async () => {
const server = Hapi.server({
port: 3000,
host: 'localhost'
});
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);
})();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: 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 * as Hapi from '@hapi/hapi';
import * as HapiSwagger from 'hapi-swagger';
// code omitted for brevity
const swaggerOptions: HapiSwagger.RegisterOptions = {
info: {
title: 'Test API Documentation'
}
};
const plugins: Array<Hapi.ServerRegisterPluginObject<any>> = [
{
plugin: Inert
},
{
plugin: Vision
},
{
plugin: HapiSwagger,
options: swaggerOptions
}
];
await server.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.
![dependabot[bot] avatar](https://avatars.githubusercontent.com/in/29110?v=4 "dependabot[bot]")
React
Typescript
Django
Laravel
Facebook
Microsoft
Google
Alibaba
D3
Tencent