optionsreference.md

9.0.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,

JSON (JSON endpoint needed to create UI)

• jsonPath: (string) The path of JSON endpoint at 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: /
• proxyPath: (string) The proxy path behind the which the API is located i.e. /my-app-name/api (note, needs to start with / and NOT end 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
  • x-* (any): any property or object with a key starting with x- is included as such in the info section of the object returned by the JSON endpoint. This allows custom properties to be defined as options and copied as such.
• tags: (array) containing array of Tag Object used to group endpoints in UI. No defaults are provided.
• grouping: (string) how to create grouping of endpoints value either path or tags - default: path
• tagsGroupingFilter: (function) A function used to determine which tags should be used for grouping (when grouping is set to tags) - default: (tag) => tag !== 'api'
• 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,
• definitionPrefix: Dynamic naming convention. default or useLabel - default: default,
• 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'
};

await server.register([
    Inert,
    Vision,
    {
        plugin: HapiSwagger,
        options: options
    }
]);

try {
    await server.start( (err) => {
    console.log('Server running at:', server.info.uri);
} catch(err) {
    console.log(err);
}
server.route(Routes);

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')
            }
        }
    }
}