redocly-cli/docs/guides/hide-specification-extensions.md

Hide OpenAPI specification extensions

When you want to hide internal operations and properties, you can follow our hide internal APIs guide. However, this approach doesn'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, see how to maintain a single source of truth (SSOT) OpenAPI definition. Then generate an internal and an external version of the API.

graph TD
    A[SSOT] -->|bundle| B(Internal)
    A[SSOT] -->|bundle| C(External)

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

Prerequisites

:::note 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:

   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:

   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, register your plugin in your Redocly configuration file redocly.yaml. Register your plugins and decorators.

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:

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

Step 4: Output internal and external APIs

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

1. Bundle the external@latest API.

   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.

   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):

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.