Hide OpenAPI specification extensions

When you want to hide internal operations and properties, you can follow our hide internal APIs guide. However, this approach won't work if you use specification extensions in your API and want to hide their details as well. For this purpose, you need a custom decorator.

Overview

In this tutorial, we'll maintain a single source of truth (SSOT) OpenAPI definition. Then, we'll generate an internal and an external version of the API.

bundle
bundle
SSOT
Internal
External

For this tutorial, we've prepared a sample containing OpenAPI specification extensions starting with x-amazon-apigateway.

Prerequisites

We do, You do

This tutorial is most effective when you follow along and complete the steps.

  • Install @redocly/cli with version 1.0.0-beta.117 or later (we use 1.0.0-beta.117 in this tutorial).
  • Download the sample.yaml file into a new directory named hide-openapi-extensions .
  • Use your favorite IDE for editing the YAML file (we use VS Code and have the Redocly extension installed).

Step 1: Create a custom plugin

In this step, create a custom plugin and define the decorator dependency.

  1. Create a new directory called plugins .
  2. In the plugins directory, create a plugin.js file with the following code:
    Copy
    Copied
    const hideOpenapiExtensions = require('./decorators/hide-openapi-extensions');
    const id = 'plugin';
    
    const decorators = {
      oas3: {
        'hide-openapi-extensions': hideOpenapiExtensions,
      },
    };
    
    module.exports = {
      id,
      decorators,
    };
  3. Save the file.
attention

You can name the plugins directory and the file anything you want. Make sure you use the correct name in the Redocly configuration file (Step 3 below).

Step 2: Add a decorator and associate it with an environment variable

  1. In the plugins directory, create a new directory called decorators .
  2. In the decorators directory, create a hide-openapi-extensions.js file with the following code:
    Copy
    Copied
    module.exports = hideOpenapiExtensions;
    
    /** @type {import('@redocly/cli').OasDecorator} */
    
    function hideOpenapiExtensions({ pattern }) {
      return {
        any: {
          enter: node => {
            pattern.forEach(item => {
              Object.keys(node).forEach(key => {
                const regex = new RegExp(item, 'i');
                if (regex.test(key)) {
                  delete node[key];
                }
              });
            });
          }
        }
      }
    }
  3. Save the file.
attention

You can name the decorators directory anything you want. Make sure you use the correct directory name in the line 1 of the plugin.js file (Step 1 above).

Step 3: Configure the plugin for use

To use the decorator, you will need to register your plugin in your Redocly configuration file redocly.yaml. Register your plugins and decorators.

Copy
Copied
apis:
  internal@latest:
    root: ./sample.yaml
  external@latest:
    root: ./sample.yaml
    decorators:
      plugin/hide-openapi-extensions:
        pattern:
          - x-amazon-apigateway
plugins:
  - "./plugins/plugin.js"
extends:
  - recommended

Make sure your hide-openapi-extensions looks as follows:

Copy
Copied
.
├── plugins
│   ├── decorators
│   │   └── hide-openapi-extensions.js
│   └── plugin.js
├── redocly.yaml
└── sample.yaml

Step 4: Output internal and external APIs

In this step, you'll produce the two API snapshots from the single source of truth. To do this, you can use the bundle command on your machine.

  1. Bundle the external@latest API.
    Copy
    Copied
    redocly bundle external@latest -o dist/bundle-external.yaml
    // or
    npx @redocly/cli bundle external@latest -o dist/bundle-external.yaml

    Inspect the file at dist/external.yaml. Confirm that all the occurrences of x-amazon-apigateway are removed.

  2. Bundle the internal@latest API.
    Copy
    Copied
    redocly bundle internal@latest -o dist/bundle-internal.yaml
    // or
    npx @redocly/cli bundle internal@latest -o dist/bundle-internal.yaml

    Inspect the file at dist/internal.yaml. Confirm that all the occurrences of x-amazon-apigateway are not removed.

Advanced usage

If you want to hide multiple specification extensions, open the redocly.yaml and add the corresponding extension names to the pattern list (after the line 9):

Copy
Copied
decorators:
  plugin/hide-openapi-extensions:
    pattern:
      - x-amazon-apigateway
      - x-another-custom-extension

Next steps

If you enjoyed this tutorial, please share it with a colleague, or on the social networks. Be sure to tag @Redocly as it lets us know how we're doing and where we can improve.

Try this technique with your own APIs to accomplish the use case demonstrated above.