An easy swagger-ui drop-in plugin for hapi (to be used with hapi-swaggered).
Clone or download
Fetching latest commit…
Cannot retrieve the latest commit at this time.
Permalink
Failed to load latest commit information.
lib
templates
test
.gitignore
.npmignore
.travis.yml
README.md
index.js
package-lock.json
package.json 3.0.2 Mar 10, 2018

README.md

hapi-swaggered-ui

Easy swagger-ui (v3) drop-in plugin for hapi to be used with hapi-swaggered.

Supports hapi 17.x and up For earlier versions check hapi-swaggered-ui 2.x (current default/latest npm install hapi-swaggered --save)

Build Status Dependency Status js-standard-style npm downloads

Install

npm install hapi-swaggered-ui@next

Configuration

  • title: string, title of swagger ui
  • path: string, optional path where the docs should be located at (e.g. '/docs', defaults to: null)
  • basePath: string, optional url base path (e.g. used to fix reverse proxy routes)
  • swaggerEndpoint: Override the auto-detection of hapi-swaggered with a specific URL. (not recommended in use with hapi-swaggered; optional)
  • swaggerOptions: object (according to swagger-ui)
    • operationsSorter: Apply a sort to the operation list of each API. It can be 'alpha' (sort by paths alphanumerically), 'method' (sort by HTTP method), null (server side sorting) or a custom function (see link above).
    • docExpansion: Controls how the API listing is displayed. It can be set to 'none' (default), 'list' (shows operations for each resource), or 'full' (fully expanded: shows operations and their details).
    • validatorUrl: By default, Swagger-UI attempts to validate specs against swagger.io's online validator (disabled for localhost). You can use this parameter to set a different validator URL, for example for locally deployed validators (Validator Badge). Setting it to false will disable validation. This parameter is relevant for Swagger 2.0 specs only.
    • In addition the following options are supported: oauth2RedirectUrl, configUrl, displayOperationId, displayRequestDuration, filter, deepLinking, maxDisplayedTags, tagsSorter, parameterMacro, modelPropertyMacro - have a look at swagger-ui
  • authorization: object - can be null or false to disable authorization through swagger-ui (e.g. in case of public apis without auth)
    • scope: string, 'query' or 'header'
    • field: string, name of the field
    • valuePrefix: string, prefix fields value (e.g. with 'bearer ')
    • defaultValue: string, default value of the api-key field
    • placeholder: string, placeholder of the api-key field
  • auth: object, auth options as specified in route options (hapi docs), will be applied to all registered plugin routes
  • defaultTags: array of strings, will be passed to the specs endpoint through the query param 'tags' (hapi-swaggered feature: tag filtering)

Example

Since hapi-swaggered exposes its plugin configuration hapi-swaggered-ui should find it's swagger endpoint automatically. In case you want to use hapi-swaggered-ui without hapi-swaggered (or the auto-detection doesn't work) you can manually set the swagger endpoint by the swaggerEndpoint option. In addition the page title can be changed through the option title.

await server.register([
  require('inert'),
  require('vision'),
  {
    plugin: require('hapi-swaggered-ui'),
    options: {
      title: 'Example API',
      path: '/docs',
      authorization: { // see above
        field: 'apiKey',
        scope: 'query', // header works as well
        // valuePrefix: 'bearer '// prefix incase
        defaultValue: 'demoKey',
        placeholder: 'Enter your apiKey here'
      },
      swaggerOptions: {} // see above
    }
  }
])

May have a look at the example listed at https://github.com/z0mt3c/hapi-swaggered