# hapi-swagger > A swagger documentation UI generator plugin for hapi Latest version **17.3.2** (published 2024-12-10) · MIT license · 0 weekly downloads ## Install ```sh npm install hapi-swagger pnpm add hapi-swagger yarn add hapi-swagger bun add hapi-swagger ``` ## Health **Score 35/100 (D)** — status: maintenance-mode. Positive: has types; no vulnerabilities; high quality score. Warnings: low downloads; no esm support. Negative: stale; low maintenance score. ## Facts | | | |---|---| | Version | 17.3.2 | | Published | 2024-12-10 | | First published | 2013-10-10 | | Weekly downloads | 0 | | License | MIT | | TypeScript types | bundled | | Module format | CommonJS | | Node | >=16.0.0 | | Dependencies | 7 | | Unpacked size | 126.4 KB | | Known vulnerabilities | 0 | | Install scripts | no | | Author | Glenn Jones | | Maintainers | glennjones, robmcguinness | | Keywords | api, docs, swagger, hapi, joi | ## Links - npm: https://www.npmjs.com/package/hapi-swagger - Repository: https://github.com/hapi-swagger/hapi-swagger - Homepage: https://github.com/hapi-swagger/hapi-swagger#readme - Issues: https://github.com/hapi-swagger/hapi-swagger/issues - npm.io page: https://npm.io/package/hapi-swagger ## Dependencies (7) - [@hapi/boom](https://npm.io/package/@hapi/boom.md) ^10.0.1 - [@hapi/hoek](https://npm.io/package/@hapi/hoek.md) ^11.0.4 - [handlebars](https://npm.io/package/handlebars.md) ^4.7.8 - [http-status](https://npm.io/package/http-status.md) ^1.7.4 - [swagger-parser](https://npm.io/package/swagger-parser.md) ^10.0.3 - [swagger-ui-dist](https://npm.io/package/swagger-ui-dist.md) ^5.17.14 - [@apidevtools/json-schema-ref-parser](https://npm.io/package/@apidevtools/json-schema-ref-parser.md) ^11.7.0 ## Alternatives - [vest](https://npm.io/package/vest.md) — 50.1K weekly downloads - [@regle/core](https://npm.io/package/@regle/core.md) — 47.0K weekly downloads - [typeof-arguments](https://npm.io/package/typeof-arguments.md) — 12.5K weekly downloads - [@lokalise/projects-engine-contracts](https://npm.io/package/@lokalise/projects-engine-contracts.md) — 978 weekly downloads - [@osjwnpm/nam-laboriosam-quibusdam](https://npm.io/package/@osjwnpm/nam-laboriosam-quibusdam.md) — 70 weekly downloads ## Recent versions - 17.3.2 (latest) — 2024-12-10 - 10.0.0-alpha.5 (next) — 2019-05-17 - 7.10.0 (v7-latest) — 2017-12-23 - 3.0.0-rc3.1 (rc) — 2015-12-01 - 17.3.1 — 2024-12-01 - 17.3.0 — 2024-08-11 - 17.2.1 — 2024-01-21 - 17.2.0 — 2023-11-04 - 17.1.0 — 2023-07-08 - 17.0.1 — 2023-07-03 - 17.0.0 — 2023-06-19 - 16.0.1 — 2023-02-23 - 16.0.0 — 2023-02-18 - 15.0.0 — 2022-11-09 - 14.5.5 — 2022-06-20 - … 148 more at https://npm.io/package/hapi-swagger/versions ## README # hapi-swagger This is a [OpenAPI (aka Swagger)](https://openapis.org/) plug-in for [Hapi](https://hapi.dev/) When installed it will self document the API interface in a project. [![Maintainers Wanted](https://img.shields.io/badge/maintainers-wanted-red.svg?style=for-the-badge)](https://github.com/hapi-swagger/hapi-swagger/issues/718) ![GitHub Workflow Status](https://img.shields.io/github/actions/workflow/status/hapi-swagger/hapi-swagger/ci.yml?style=for-the-badge) [![npm downloads](https://img.shields.io/npm/dm/hapi-swagger.svg?style=for-the-badge)](https://www.npmjs.com/package/hapi-swagger) [![MIT license](http://img.shields.io/badge/license-MIT-blue.svg?style=for-the-badge)](https://raw.github.com/hapi-swagger/hapi-swagger/master/license.txt) ## Compatibility | Version | [Hapi](https://github.com/hapijs/hapi) | [Joi](https://github.com/sideway/joi) | Node | Release Notes | | ------- | -------------------------------------- | ------------------------------------- | ------ | --------------------------------------------------------------- | | `17.x` | `>=20.0.0 @hapi/hapi` | `>=17.0.0 joi` | `>=16` | [Release](https://github.com/hapi-swagger/hapi-swagger/releases/tag/v17.0.0) | | `16.x` | `>=20.0.0 @hapi/hapi` | `>=17.0.0 joi` | `>=14` | [#795](https://github.com/hapi-swagger/hapi-swagger/issues/795) | | `15.x` | `>=20.0.0 @hapi/hapi` | `>=17.0.0 joi` | `>=14` | [#782](https://github.com/hapi-swagger/hapi-swagger/issues/782) | | `14.x` | `>=19.0.0 @hapi/hapi` | `>=17.0.0 joi` | `>=12` | [#680](https://github.com/hapi-swagger/hapi-swagger/issues/680) | | `13.x` | `>=19.0.0 @hapi/hapi` | `>=17.0.0 @hapi/joi` | `>=12` | [#660](https://github.com/hapi-swagger/hapi-swagger/issues/660) | | `12.x` | `>=19.0.0 @hapi/hapi` | `>=17.0.0 @hapi/joi` | `>=12` | [#644](https://github.com/hapi-swagger/hapi-swagger/issues/644) | | `11.x` | `>=18.4.0 @hapi/hapi` | `>=16.0.0 @hapi/joi` | `>=8` | [#631](https://github.com/hapi-swagger/hapi-swagger/issues/631) | | `10.x` | `>=18.3.1 @hapi/hapi` | `>=14.0.0 @hapi/joi` | `>=8` | [#587](https://github.com/hapi-swagger/hapi-swagger/issues/587) | | `9.x` | `>=17 hapi` | `<14.0.0` | `>=8` | [#487](https://github.com/hapi-swagger/hapi-swagger/issues/487) | | `7.x` | `<17 hapi` | ??? | ??? | [#325](https://github.com/hapi-swagger/hapi-swagger/issues/325) | ## Installation You can add the module to your Hapi using npm: ```bash > npm install hapi-swagger --save ``` **hapi-swagger** no longer bundles `joi` to fix [#648](https://github.com/hapi-swagger/hapi-swagger/issues/648). Install **hapi-swagger** with peer dependencies using: ```bash npx install-peerdeps hapi-swagger ``` 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. ```bash > npm install @hapi/inert --save > npm install @hapi/vision --save ``` ## Documentation - [Options Reference](optionsreference.md) - [Usage Guide](usageguide.md) ## Quick start In 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](https://hapi.dev/). ```Javascript 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); })(); ``` ### 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). ```Javascript { 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`. ### Typescript **hapi-swagger** exports its own typescript definition file that can be used when registering the plugin with **Hapi**. See example below: #### Install Typescript Definition Files ```sh npm i @types/hapi__hapi @types/hapi__inert @types/hapi__joi @types/hapi__vision @types/node hapi-swagger --save-dev ``` #### Register Plugin with Typescript ```typescript import * 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> = [ { plugin: Inert }, { plugin: Vision }, { plugin: HapiSwagger, options: swaggerOptions } ]; await server.register(plugins); ``` ## Contributing Read the [contributing guidelines](./.github/CONTRIBUTING.md) 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. --- _Source: https://npm.io/package/hapi-swagger · Machine-readable twin of the npm.io package page. Health data is recomputed on every publish._