optionsreference.md

7.6.0 Options Reference

Plugin Options

URLs and plugin

• schemes: (array) The transfer protocol of the API ie ['http']
• host: (string) The host (name or IP) serving the API including port if any i.e. localhost:8080
• auth: (boolean, string or object) defines security strategy to use for plugin resources - default: false,
• cors: (boolean) weather the swagger.json routes is servered with cors support - default: false,
• connectionLabel: (string) A label used to document an API on a different HAPI server connection

JSON (JSON endpoint needed to create UI)

• jsonPath: (string) The path of JSON endpoint that describes the API - default: /swagger.json
• basePath: (string) The base path from where the API starts i.e. /v2/ (note, needs to start with /) - default: /
• pathPrefixSize: (number) Selects what segment of the URL path is used to group endpoints - default: 1
• pathReplacements : (array) methods for modifying path and group names in documentation - default: []
• info
  • title (string) The title of the application - default: API documentation
  • version (string) The version number of the API - default: 0.0.1
  • description (string) A short description of the application
  • termsOfService (string) A URL to the Terms of Service of the API
  • contact
    • name (string) A contact name for the API
    • url (string) A URL pointing to the contact information. MUST be formatted as a URL
    • email (string) A email address of the contact person/organization. MUST be formatted as an email address.
  • license
    • name (string) The name of the license used for the API
    • url (string) The URL to the license used by the API. MUST be formatted as a URL
• tags: (array) containing array of Tag Object used to group endpoints in UI. No defaults are provided.
• securityDefinitions:: (object) Containing Security Definitions Object. No defaults are provided.
• payloadType: (string) How payload parameters are displayed json or form - default: json
• consumes: (array) The mimetypes consumed - default: ['application/json']
• produces: (array) The mimetypes produced - default: ['application/json']
• xProperties: Adds JOI data that cannot be use directly by swagger as metadata - default: true,
• reuseDefinitions: Reuse of definition models to save space - default: true,
• deReference: Dereferences JSON output - default: false,
• debug: Validates the JSON ouput against swagger specification - default: false,

UI

• swaggerUI: (boolean) Add files that support SwaggerUI. Only removes files if documentationPage is also set to false - default: true
• swaggerUIPath: (string) The path of to all the SwaggerUI resources - default: /swaggerui/
• documentationPage: (boolean) Add documentation page - default: true
• documentationPath: (string) The path of the documentation page - default: /documentation
• expanded: (string) If UI is expanded when opened. none, list or full - default: list
• jsonEditor: (boolean) If UI should use JSON Edtior - default: false
• sortTags: (string) a sort method for tags i.e. groups in UI. default or name
• sortEndpoints: (string) a sort method for endpoints in UI. path, method, ordered
• lang: (string) The language of the UI en, es, fr, it, ja, pl, pt, ru, tr or zh-cn - default: en
• uiCompleteScript: (string) A JavaScript string injected into the HTML, called when UI loads - default: null
• validatorUrl: (string || null) sets the external validating URL Can swtich off by setting to null

Route Options

• payloadType: (string) How payload parameters are displayed json or form - default: json
• responses: (object) a collection of example responses for each HTTP statuses
• consumes: (array) The mimetypes consumed - default: ['application/json']
• produces: (array) The mimetypes produced - default: ['application/json']
• validate
  • params : (JOI object) allows you to param route documentation outside of HAPI validation
  • query : (JOI object) allows you to query route documentation outside of HAPI validation
  • headers : (JOI object) allows you to headers route documentation outside of HAPI validation
  • payload : (JOI object) allows you to payload route documentation outside of HAPI validation
• security : Hoek.reach(routeOptions, 'security') || null,
• order: (int) The order in which endpoints are displayed, works with options.sortEndpoints = 'ordered'
• deprecated: (boolean) Whether a endpoint has been deprecated - default: false

Plugin options example

The plugin level options are added as you register the hapi-swagger plugin.

const options = {
        'info': {
            'title': 'Test API Documentation',
            'version': '5.14.3',
            'contact': {
                'name': 'Glenn Jones',
                'email': 'glenn@example.com'
        },
        'schemes': ['https'],
        'host': 'example.com'
    };

server.register([
    require('inert'),
    require('vision'),
    {
        require('hapi-swagger'),
        options: options
    }],
    (err) => {

        if (err) {
            console.log(err);
        }

        server.route(Routes);

        server.start((err) => {
            if (err) {
                console.log(err);
            } else {
                console.log('Server running at:', server.info.uri);
            }
        });
    });

Route options example

The route level options are always placed within the plugins.hapi-swagger object under config. These options are only assigned to the route they are apply to.

{
    method: 'PUT',
    path: '/store/{id}',
    config: {
        handler: handlers.storeUpdate,
        plugins: {
            'hapi-swagger': {
                responses: {
                    '400': {
                        'description': 'BadRequest'
                    }
                },
                payloadType: 'form'
            }
        },
        tags: ['api'],
        validate: {
            payload: {
                a: Joi.number().required().description('the first number')
            }
        }
    }
}