Configuration

ⓘ

OAS Tools v3 can read the v2 options and parse them. However, some of the new features will not be available if using the v2 initialization. Check the Compatibility page for more information

Options

General config

This options are set at the root level of the configuration object. They are general purpose options that affect mainly the initialization of the framework.

Option	Type	Default	Description
packageJSON	String	`./package.json`	Path to where the package.json file is located
oasFile	String	`./api/oas-file.yaml`	Path to where the main OpenAPI document is located
useAnnotations (Experimental)	Boolean	`false`	This feature is experimental. Toggles JSDoc like annotations. Check the routing section for more information

Logger config

This options affect the default logger integrated within the OAS Tools core library. They are set under the logger key in the configuration object.

Option	Type	Default	Description
customLogger	Object	`null`	Custom logger to override the built-in one. Must be a winston instance. Setting this option causes to ignore the rest.
level	String	`info`	Level of the logs that are printed to console
logFile	Boolean	`false`	Whether to save the logs to a file or not.
logFilePath	String	`./logs/oas-tools.log`	Path where the log file is saved. Ignored if logFile is `false`.

Middleware config

This options are set under middleware.<middleware name>. They set the configuration for each of the built-in middleware function of OAS Tools.

Option	Type	Default	Description
router.disable	Boolean	`false`	Toggles Router middleware.
router.controllers	String	`./controllers`	Path to the controllers directory.
validator.requestValidation	Boolean	`true`	Toggles Request validation.
validator.responseValidation	Boolean	`true`	Toggles Response validation.
validator.strict	Boolean	`false`	When active, throws an error upon validation errors. In other case, prints a warn message.
security.disable	Boolean	`true`	Toggles security middleware.
security.auth	Object	`null`	Object containing the handler functions for the security schemes. Check the security section for more information.
swagger.disable	Boolean	`false`	Toggles SwaggerUI.
swagger.path	String	`/docs`	Path where the SwaggerUI will be displayed.
swagger.ui	Object	`null`	Custom configuration for the Swagger interface. Check swagger-ui package docs for more information.
error.disable	Boolean	`false`	Toggles the built-in error handler.
error.printStackTrace	Boolean	`false`	Prints the full trace when an error is thrown.
error.customHandler	Function	`null`	Function to extend the built-in handler. Check the error handler section for more information.

Setting configuration

Configuration for OAS Tools can be set in multiple ways, why is why we have established a preference order for the possible configuration sources:

Using package.json

Configuration can be set in the package json under the oas-tools keyword. For example if we wanted to disable error handling and set the logger level to debug:

// package.json

{
  "oas-tools": {
    "logger": { "level": "debug" },
    "middleware": { "error": { "disable": true } }
  }

  ...
}

The rc config uses the rc config loader to load the configuration from multiple sources, following precedence order. Although it allows setting configuration from environment variables or global config files at /etc or $HOME/config, typically you'll want to use a local file located in your proyect root. That file must be named .oastoolsrc and can be written using ini or JSON syntax:

// .oastoolsrc
{
    "oasFile": "api/main.yaml",
    "logger": { "level": "off" }, // setting off or false to logger level deactivates it
    "useAnnotations": true,
    "middleware": {
        "validator": {
            "strict": true
        }
    }
}

Passing an object

Finally, you can pass a configuration object directly to the OAS Tools initialization function. This approach is best when you require declaring function like security handlers or custom logger classes.

Take into account that this approach has the maximum priority and will override any other configuration previously set through any other means.

// index.js

const http = require('http');
const express = require("express");
const oasTools = require("@oas-tools/core");
const app = express();

app.use(express.json());
var serverPort = 8080;

const config = {
    middleware: {
        security: {
            disable: false,
            auth: {
                apikey: (token) => { /* ApiKey security handler */ }
            }
        }
    }
}

oasTools.initialize(app, config).then(() => {
    http.createServer(app).listen(serverPort, () => console.log("Server started!"));
})

In case you need to set complex config options, or your entrypoint file readibility is being compromised, it is a good practise to declare the configuration in a separate file, like so:

// oastools.config.js

module.exports = {
    middleware: {
        security: {
            disable: false,
            auth: {
                apikey: (token) => { /* ApiKey security handler */ }
            }
        }
    }
}

And then import it in the entrypoint file:

// index.js

const http = require('http');
const app = require("express");
const oasTools = require("@oas-tools/core");
const config = require("./oastools.config.js");

const app = express();

app.use(express.json());
var serverPort = 8080;

oasTools.initialize(app, config).then(() => {
    http.createServer(app).listen(serverPort, () => console.log("Server started!"));
})