{"id":13465050,"url":"https://github.com/hapi-swagger/hapi-swagger","last_synced_at":"2025-12-16T23:04:55.843Z","repository":{"id":9891281,"uuid":"11896413","full_name":"hapi-swagger/hapi-swagger","owner":"hapi-swagger","description":"A Swagger interface for hapi","archived":false,"fork":false,"pushed_at":"2025-03-17T19:16:22.000Z","size":8742,"stargazers_count":912,"open_issues_count":91,"forks_count":423,"subscribers_count":26,"default_branch":"master","last_synced_at":"2025-03-21T03:12:14.483Z","etag":null,"topics":["hapi"],"latest_commit_sha":null,"homepage":"https://hapi.dev/","language":"JavaScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/hapi-swagger.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":".github/CONTRIBUTING.md","funding":null,"license":"license.txt","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2013-08-05T11:13:40.000Z","updated_at":"2025-03-09T00:16:53.000Z","dependencies_parsed_at":"2023-10-21T11:35:13.093Z","dependency_job_id":"f4889fef-14b8-4916-888b-097d09c7da10","html_url":"https://github.com/hapi-swagger/hapi-swagger","commit_stats":{"total_commits":963,"total_committers":177,"mean_commits":5.440677966101695,"dds":0.6947040498442367,"last_synced_commit":"d768b5c017ed0b27b9a518b81c97b66040115421"},"previous_names":["glennjones/hapi-swagger"],"tags_count":130,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/hapi-swagger%2Fhapi-swagger","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/hapi-swagger%2Fhapi-swagger/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/hapi-swagger%2Fhapi-swagger/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/hapi-swagger%2Fhapi-swagger/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/hapi-swagger","download_url":"https://codeload.github.com/hapi-swagger/hapi-swagger/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":245351747,"owners_count":20601090,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["hapi"],"created_at":"2024-07-31T14:00:56.183Z","updated_at":"2025-12-16T23:04:55.757Z","avatar_url":"https://github.com/hapi-swagger.png","language":"JavaScript","readme":"# hapi-swagger\n\nThis is a [OpenAPI (aka Swagger)](https://openapis.org/) plug-in for [Hapi](https://hapi.dev/) When installed it will self document the API interface\nin a project.\n\n[![Maintainers Wanted](https://img.shields.io/badge/maintainers-wanted-red.svg?style=for-the-badge)](https://github.com/hapi-swagger/hapi-swagger/issues/718)\n![GitHub Workflow Status](https://img.shields.io/github/actions/workflow/status/hapi-swagger/hapi-swagger/ci.yml?style=for-the-badge)\n[![npm downloads](https://img.shields.io/npm/dm/hapi-swagger.svg?style=for-the-badge)](https://www.npmjs.com/package/hapi-swagger)\n[![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)\n\n## Compatibility\n\n| Version | [Hapi](https://github.com/hapijs/hapi) | [Joi](https://github.com/sideway/joi) | Node   | Release Notes                                                   |\n| ------- | -------------------------------------- | ------------------------------------- | ------ | --------------------------------------------------------------- |\n| `17.x`  | `\u003e=20.0.0 @hapi/hapi`                  | `\u003e=17.0.0 joi`                        | `\u003e=16` | [Release](https://github.com/hapi-swagger/hapi-swagger/releases/tag/v17.0.0)                                                           |\n| `16.x`  | `\u003e=20.0.0 @hapi/hapi`                  | `\u003e=17.0.0 joi`                        | `\u003e=14` | [#795](https://github.com/hapi-swagger/hapi-swagger/issues/795) |\n| `15.x`  | `\u003e=20.0.0 @hapi/hapi`                  | `\u003e=17.0.0 joi`                        | `\u003e=14` | [#782](https://github.com/hapi-swagger/hapi-swagger/issues/782) |\n| `14.x`  | `\u003e=19.0.0 @hapi/hapi`                  | `\u003e=17.0.0 joi`                        | `\u003e=12` | [#680](https://github.com/hapi-swagger/hapi-swagger/issues/680) |\n| `13.x`  | `\u003e=19.0.0 @hapi/hapi`                  | `\u003e=17.0.0 @hapi/joi`                  | `\u003e=12` | [#660](https://github.com/hapi-swagger/hapi-swagger/issues/660) |\n| `12.x`  | `\u003e=19.0.0 @hapi/hapi`                  | `\u003e=17.0.0 @hapi/joi`                  | `\u003e=12` | [#644](https://github.com/hapi-swagger/hapi-swagger/issues/644) |\n| `11.x`  | `\u003e=18.4.0 @hapi/hapi`                  | `\u003e=16.0.0 @hapi/joi`                  | `\u003e=8`  | [#631](https://github.com/hapi-swagger/hapi-swagger/issues/631) |\n| `10.x`  | `\u003e=18.3.1 @hapi/hapi`                  | `\u003e=14.0.0 @hapi/joi`                  | `\u003e=8`  | [#587](https://github.com/hapi-swagger/hapi-swagger/issues/587) |\n| `9.x`   | `\u003e=17 hapi`                            | `\u003c14.0.0`                             | `\u003e=8`  | [#487](https://github.com/hapi-swagger/hapi-swagger/issues/487) |\n| `7.x`   | `\u003c17 hapi`                             | ???                                   | ???    | [#325](https://github.com/hapi-swagger/hapi-swagger/issues/325) |\n\n## Installation\n\nYou can add the module to your Hapi using npm:\n\n```bash\n\u003e npm install hapi-swagger --save\n```\n\n**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:\n\n```bash\nnpx install-peerdeps hapi-swagger\n```\n\nIf 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\ncontent serving.\n\n```bash\n\u003e npm install @hapi/inert --save\n\u003e npm install @hapi/vision --save\n```\n\n## Documentation\n\n-   [Options Reference](optionsreference.md)\n-   [Usage Guide](usageguide.md)\n\n## Quick start\n\nIn your Hapi apps please check the main JavaScript file and add the following code to already created a Hapi `server` object.\nYou will also add the routes for you API as describe on [hapi website](https://hapi.dev/).\n\n```Javascript\nconst Hapi = require('@hapi/hapi');\nconst Inert = require('@hapi/inert');\nconst Vision = require('@hapi/vision');\nconst HapiSwagger = require('hapi-swagger');\nconst Pack = require('./package');\n\n(async () =\u003e {\n    const server = Hapi.server({\n        port: 3000,\n        host: 'localhost'\n    });\n\n    const swaggerOptions = {\n        info: {\n                title: 'Test API Documentation',\n                version: Pack.version,\n            },\n        };\n\n    await server.register([\n        Inert,\n        Vision,\n        {\n            plugin: HapiSwagger,\n            options: swaggerOptions\n        }\n    ]);\n\n    try {\n        await server.start();\n        console.log('Server running at:', server.info.uri);\n    } catch(err) {\n        console.log(err);\n    }\n\n    server.route(Routes);\n})();\n```\n\n### Tagging your API routes\n\nAs a project may be a mixture of web pages and API endpoints you need to tag the routes you wish Swagger to\ndocument. Simply add the `tags: ['api']` property to the route object for any endpoint you want documenting.\n\nYou can even specify more tags and then later generate tag-specific documentation. If you specify\n`tags: ['api', 'foo']`, you can later use `/documentation?tags=foo` to load the documentation on the\nHTML page (see next section).\n\n```Javascript\n{\n    method: 'GET',\n    path: '/todo/{id}/',\n    options: {\n        handler: handlers.getToDo,\n        description: 'Get todo',\n        notes: 'Returns a todo item by the id passed in the path',\n        tags: ['api'], // ADD THIS TAG\n        validate: {\n            params: Joi.object({\n                id : Joi.number()\n                        .required()\n                        .description('the id for the todo item'),\n            })\n        }\n    },\n}\n```\n\nOnce you have tagged your routes start the application. **The plugin adds a page into your site with the route `/documentation`**,\nso the the full URL for the above options would be `http://localhost:3000/documentation`.\n\n### Typescript\n\n**hapi-swagger** exports its own typescript definition file that can be used when registering the plugin with **Hapi**. See example below:\n\n#### Install Typescript Definition Files\n\n```sh\nnpm i @types/hapi__hapi @types/hapi__inert @types/hapi__joi @types/hapi__vision @types/node hapi-swagger --save-dev\n```\n\n#### Register Plugin with Typescript\n\n```typescript\nimport * as Hapi from '@hapi/hapi';\nimport * as HapiSwagger from 'hapi-swagger';\n\n// code omitted for brevity\n\nconst swaggerOptions: HapiSwagger.RegisterOptions = {\n    info: {\n        title: 'Test API Documentation'\n    }\n};\n\nconst plugins: Array\u003cHapi.ServerRegisterPluginObject\u003cany\u003e\u003e = [\n    {\n        plugin: Inert\n    },\n    {\n        plugin: Vision\n    },\n    {\n        plugin: HapiSwagger,\n        options: swaggerOptions\n    }\n];\n\nawait server.register(plugins);\n```\n\n## Contributing\n\nRead the [contributing guidelines](./.github/CONTRIBUTING.md) for details.\n\n## Thanks\n\nI 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.\n","funding_links":[],"categories":["JavaScript"],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fhapi-swagger%2Fhapi-swagger","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fhapi-swagger%2Fhapi-swagger","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fhapi-swagger%2Fhapi-swagger/lists"}