# Hide OpenAPI specification extensions

When you want to hide internal operations and properties, you can follow our [hide internal APIs](/docs/cli/v1/guides/hide-apis) guide.
However, this approach doesn't work if you use [specification extensions](https://redocly.com/docs/openapi-visual-reference/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 description.
Then generate an internal and an external version of the API.

```mermaid
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

**We do, You do**

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

- [Install @redocly/cli](/docs/cli/v1/installation) with version 1.0.0-beta.117 or later (we use 1.0.0-beta.117 in this tutorial).
- Download the [sample.yaml](https://gist.github.com/bandantonio/e1331ba5afd24485de5e6229c91d25ed) 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](https://redocly.com/docs/redocly-openapi/) 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:

  ```js
  const hideOpenapiExtensions = require('./decorators/hide-openapi-extensions');
  const id = 'plugin';

  const decorators = {
    oas3: {
      'hide-openapi-extensions': hideOpenapiExtensions,
    },
  };

  module.exports = function hideExtensionsPlugin() {
    return {
      id,
      decorators,
    };
  };
  ```
3. Save the file.

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:

  ```js
  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.

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`.

```yaml
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:

```bash
.
├── 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](/docs/cli/v1/commands/bundle) on your machine.

1. Bundle the `external@latest` API.

  ```bash
  redocly bundle external@latest -o dist/bundle-external.yaml
  // or
  npx @redocly/cli@latest 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.

  ```bash
  redocly bundle internal@latest -o dist/bundle-internal.yaml
  // or
  npx @redocly/cli@latest 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):

```yaml
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.