{"ast":{"$$mdtype":"Tag","name":"article","attributes":{},"children":[{"$$mdtype":"Tag","name":"Heading","attributes":{"level":1,"id":"hide-openapi-specification-extensions","__idx":0},"children":["Hide OpenAPI specification extensions"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["When you want to hide internal operations and properties, you can follow our ",{"$$mdtype":"Tag","name":"Link","attributes":{"href":"/docs/cli/v2/guides/hide-apis"},"children":["hide internal APIs"]}," guide."," ","However, this approach doesn't work if you use ",{"$$mdtype":"Tag","name":"Link","attributes":{"href":"https://redocly.com/docs/openapi-visual-reference/specification-extensions/"},"children":["specification extensions"]}," ","in your API and want to hide their details as well. For this purpose, you need a custom decorator."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"overview","__idx":1},"children":["Overview"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["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."]},{"$$mdtype":"Tag","name":"Diagram","attributes":{"data-language":"mermaid","diagramType":"mermaid","diagramSource":"graph TD\n A[SSOT] -->|bundle| B(Internal)\n A[SSOT] -->|bundle| C(External)\n","diagramHtml":"

bundle

bundle

SSOT

Internal

External

","diagramHtmlDark":"

bundle

bundle

SSOT

Internal

External

"},"children":[]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["For this tutorial, we've prepared a sample containing OpenAPI specification extensions starting with ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["x-amazon-apigateway"]},"."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"prerequisites","__idx":2},"children":["Prerequisites"]},{"$$mdtype":"Tag","name":"Admonition","attributes":{"type":"info","name":"We do, You do"},"children":[{"$$mdtype":"Tag","name":"p","attributes":{},"children":["This tutorial is most effective when you follow along and complete the steps."]}]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"Link","attributes":{"href":"/docs/cli/v2/installation"},"children":["Install @redocly/cli"]}," with version 1.0.0-beta.117 or later (we use 1.0.0-beta.117 in this tutorial)."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Download the ",{"$$mdtype":"Tag","name":"Link","attributes":{"href":"https://gist.github.com/bandantonio/e1331ba5afd24485de5e6229c91d25ed"},"children":["sample.yaml"]}," file into a new directory named ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["hide-openapi-extensions"]},"."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Use your favorite IDE for editing the YAML file (we use VS Code and have the ",{"$$mdtype":"Tag","name":"Link","attributes":{"href":"https://redocly.com/docs/redocly-openapi/"},"children":["Redocly extension"]}," installed)."]}]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"step-1-create-a-custom-plugin","__idx":3},"children":["Step 1: Create a custom plugin"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["In this step, create a custom plugin and define the decorator dependency."]},{"$$mdtype":"Tag","name":"ol","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Create a new directory called ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["plugins"]},"."]}]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"p","attributes":{},"children":["In the ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["plugins"]}," directory, create a ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["plugin.js"]}," file with the following code:"]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"js","header":{"controls":{"copy":{}}},"source":"import hideOpenapiExtensions from './decorators/hide-openapi-extensions.js';\n\nconst decorators = {\n oas3: {\n 'hide-openapi-extensions': hideOpenapiExtensions,\n },\n};\n\nexport default function hideExtensionsPlugin() {\n return {\n id: 'plugin',\n decorators,\n };\n}\n","lang":"js"},"children":[]}]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Save the file."]}]}]},{"$$mdtype":"Tag","name":"Admonition","attributes":{"type":"info"},"children":[{"$$mdtype":"Tag","name":"p","attributes":{},"children":["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)."]}]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"step-2-add-a-decorator-and-associate-it-with-an-environment-variable","__idx":4},"children":["Step 2: Add a decorator and associate it with an environment variable"]},{"$$mdtype":"Tag","name":"ol","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"p","attributes":{},"children":["In the ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["plugins"]}," directory, create a new directory called ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["decorators"]},"."]}]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"p","attributes":{},"children":["In the ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["decorators"]}," directory, create a ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["hide-openapi-extensions.js"]}," file with the following code:"]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"js","header":{"controls":{"copy":{}}},"source":"/** @type {import('@redocly/cli').OasDecorator} */\nexport default function hideOpenapiExtensions({ pattern }) {\n return {\n any: {\n enter: (node) => {\n pattern.forEach((item) => {\n Object.keys(node).forEach((key) => {\n const regex = new RegExp(item, 'i');\n if (regex.test(key)) {\n delete node[key];\n }\n });\n });\n },\n },\n };\n}\n","lang":"js"},"children":[]}]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Save the file."]}]}]},{"$$mdtype":"Tag","name":"Admonition","attributes":{"type":"info"},"children":[{"$$mdtype":"Tag","name":"p","attributes":{},"children":["You can name the decorators directory anything you want. Make sure you use the correct directory name in the line 1 of the ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["plugin.js"]}," file (Step 1 above)."]}]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"step-3-configure-the-plugin-for-use","__idx":5},"children":["Step 3: Configure the plugin for use"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["To use the decorator, register your plugin in your Redocly configuration file ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["redocly.yaml"]},". Register your ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["plugins"]}," and ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["decorators"]},"."]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"yaml","header":{"controls":{"copy":{}}},"source":"apis:\n internal@latest:\n root: ./sample.yaml\n external@latest:\n root: ./sample.yaml\n decorators:\n plugin/hide-openapi-extensions:\n pattern:\n - x-amazon-apigateway\nplugins:\n - ./plugins/plugin.js\nextends:\n - recommended\n","lang":"yaml"},"children":[]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Make sure your ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["hide-openapi-extensions"]}," looks as follows:"]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"bash","header":{"controls":{"copy":{}}},"source":".\n├── plugins\n│ ├── decorators\n│ │ └── hide-openapi-extensions.js\n│ └── plugin.js\n├── redocly.yaml\n└── sample.yaml\n","lang":"bash"},"children":[]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"step-4-output-internal-and-external-apis","__idx":6},"children":["Step 4: Output internal and external APIs"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["In this step, two API snapshots are produced from the single source of truth. To do this, you can use the ",{"$$mdtype":"Tag","name":"Link","attributes":{"href":"/docs/cli/v2/commands/bundle"},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["bundle"]}," command"]}," on your machine."]},{"$$mdtype":"Tag","name":"ol","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Bundle the ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["external@latest"]}," API."]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"bash","header":{"controls":{"copy":{}}},"source":"redocly bundle external@latest -o dist/bundle-external.yaml\n// or\nnpx @redocly/cli@latest bundle external@latest -o dist/bundle-external.yaml\n","lang":"bash"},"children":[]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Inspect the file at ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["dist/external.yaml"]},"."," ","Confirm that all the occurrences of ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["x-amazon-apigateway"]}," are removed."]}]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Bundle the ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["internal@latest"]}," API."]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"bash","header":{"controls":{"copy":{}}},"source":"redocly bundle internal@latest -o dist/bundle-internal.yaml\n// or\nnpx @redocly/cli@latest bundle internal@latest -o dist/bundle-internal.yaml\n","lang":"bash"},"children":[]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Inspect the file at ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["dist/internal.yaml"]},"."," ","Confirm that all the occurrences of ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["x-amazon-apigateway"]}," are ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["not"]}," removed."]}]}]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"advanced-usage","__idx":7},"children":["Advanced usage"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["If you want to hide multiple specification extensions, open the ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["redocly.yaml"]}," and add the corresponding extension names"," ","to the ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["pattern"]}," list (after the line 9):"]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"yaml","header":{"controls":{"copy":{}}},"source":"decorators:\n plugin/hide-openapi-extensions:\n pattern:\n - x-amazon-apigateway\n - x-another-custom-extension\n","lang":"yaml"},"children":[]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"next-steps","__idx":8},"children":["Next steps"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["If you enjoyed this tutorial, please share it with a colleague, or on the social networks."," ","Be sure to tag ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["@Redocly"]}," as it lets us know how we're doing and where we can improve."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Try this technique with your own APIs to accomplish the use case demonstrated above."]}]},"frontmatter":{},"tagList":["admonition"],"title":"Hide OpenAPI specification extensions","lastModified":"2026-05-18T14:03:00.000Z"}