@ama-openapi/redocly-plugin

Ama OpenAPI Redocly Plugin

Experimental: This package is available in early access, the final version will be released in v15.

A Redocly CLI plugin for managing OpenAPI dependencies and masking operations based on @ama-openapi/core.

Overview

This plugin extends the Redocly CLI with functionality to handle OpenAPI dependency setup and content masking. It leverages the core dependency management system provided by @ama-openapi/core to automatically resolve and integrate OpenAPI dependencies in your specifications.

Features

• Dependency management: Automatically resolves and manages OpenAPI dependencies
• Content masking: Applies masking rules to hide or transform sensitive information in OpenAPI specifications
• Redocly integration: Seamlessly integrates with the Redocly CLI toolchain
• Configurable: Supports custom configuration for dependency resolution and masking rules

Installation

npm install @ama-openapi/redocly-plugin

Usage

Basic Configuration

Add the plugin to your Redocly configuration file (.redocly.yaml or redocly.yaml):

plugins:
  - '@ama-openapi/redocly-plugin'

Dependency Retrieval

The plugin retrieves dependencies defined in your OpenAPI Configuration:

// in the package.json file
{
  "name": "@my/specification",
  "dependencies": {
    "@specification/pet-store": "latest"
  }
}

# in the openapi.manifest.yaml
models:
  "@specification/pet-store": "models/pet.v1.yaml"

# in your specification
openapi: 3.0.0
info:
  title: My API
  version: 1.0.0

content:
  application/json:
    schema:
      type: object
        properties:
          data:
            $ref: './specification/pet-store/models/pet.v1.yaml'

Find the documentation regarding the package management strategy on Node Package Manager.
Find a complete documentation regarding the Manifest on the OpenAPI Configuration.

Masking Configuration

A full documentation on masking specified information is available in OpenAPI Masking configuration.
A simple example can be:

# in the openapi.manifest.yaml
models:
  "@specification/pet-store":
    - path: "models/pet.v1.yaml"
      transform:
        - fileRename: "my-$1"
          mask:
            properties:
              exampleField:

Available plugin configurations

As the plugin must be executed at the initialization of the Redocly process, the configuration of the plugin should be provided via environment variables.

The following environment variables are supported:

Environment Variable	Description	Default Value
AMA_OPENAPI_REDOCLY_CONTINUE_ON_ERROR	Ignore process failure and continue Redocly process	false
AMA_OPENAPI_REDOCLY_VERBOSE	Display debug level logs	false
AMA_OPENAPI_REDOCLY_QUIET	Suppress all output	false

Additional custom decorators

The plugin offer additional Redocly decorator which can be selected and configured in Redocly configuration.

The full list of available decorators, along with their options, is provided in the dedicated documentation.

Integration

This Redocly Plugin is designed to work with the following tools:

• @ama-openapi/core: Core dependency management functionality
• @ama-openapi/cli: Command to manually retrieve the dependencies
• @ama-openapi/create: Project scaffolding tool