Last updated

Custom plugins

Custom plugins are a powerful way to extend Redocly. Use of custom plugins requires in-depth knowledge of the document type (such as OpenAPI) that you are working with, JavaScript coding skills, and the plugin interface. Custom plugins are recommended for advanced users who have exhausted the built-in options available, and who can develop JavaScript extensions themselves. Each plugin is a JavaScript module which can export custom rules, configurations, preprocessors, decorators or type tree extensions.

For many users, our highly configurable rules cover their needs without needing a custom plugin.

Custom plugins use the visitor pattern to traverse the document structure and apply the rules and decorators (and preprocessors if you have them) to each element. Rules defined in custom plugins may need additional context available, and this can be achieved using the nested visitor approach (please note that nested visitors are not available for decorators or preprocessors).

Extend Redocly with custom plugins

Custom plugins can extend the built-in functionality of Redocly in the following ways:

Add custom plugins to your project

Each plugin can contain any or many of each type of extension (rules, configuration, decorators, etc).

Define the plugins to include in the redocly.yaml configuration file, in the plugins section:

plugins:
  - plugins/my-best-plugin.js
  - plugins/another-plugin.js

The paths are relative to the configuration file location. Where there are multiple features that happen at the same time, such as decorators, the plugins loaded first in the plugins section are processed first.

Plugin structure

The minimal plugin should export a function that returns an object with a single property id that is used to refer to the contents of the plugin in the redocly.yaml configuration file:

module.exports = function myPlugin() {
  return {
    id: 'my-local-plugin',
  };
};

Supported formats

Everything that is exported from a plugin relates to one of the supported document formats, such as OpenAPI v3. Plugins work by exporting an object containing a key-value mapping from a document format and version (oas2 or oas3 are supported) to an extension object (rules, preprocessors, decorators).

Before processing the API description document, Redocly CLI detects the document format and applies a corresponding set of extensions.