filter-out

Removes nodes that have specific property set to the specific value and preserves others. Nodes that don't have the property defined are not impacted.

Applies to any node type defined by the applyTo option. If applyTo is not set, applies to all nodes where the property is declared.

API design principles

Giant monolithic API docs can be overwhelming. By filtering what is most relevant to the audience, they can focus on what is most relevant and not be overwhelmed or distracted by all of the other API operations.

Configuration

Option	Type	Description
property	string	REQUIRED. The property name used for evaluation. It attempts to match the values.
value	[string]	REQUIRED. List of values used for the matching.
matchStrategy	string	Possible values: `all`, `any`. If `all` it needs to match all of the values supplied. If `any` it needs to match only one of the values supplied. Default value: `any`.
applyTo	string	Possible values: `PathItem`, `Operation`. When set, filtering is scoped to the specified target.

Examples

Remove operations by tag

Using the Museum API (v1.0.0), use the stats command to get a summary of its contents:

redocly stats openapi.yaml

I'm interested in the paths and operations in particular:

Path Items: 5
Operations: 8

This example filters out all the endpoints tagged "Events", and redocly.yaml looks like this:

apis:
  filterout:
    root: openapi.yaml
    decorators:
      filter-out:
        property: tags
        value: Events
        applyTo: Operation

To apply the decorator to the OpenAPI description, run the bundle command, like this:

redocly bundle filterout -o museum-filtered.yaml

Open the output file, museum-filtered.yaml, and the endpoints relating to special events have all been removed. Repeat the stats command, and this time the numbers are reported as:

Path Items: 3
Operations: 3

This filtered OpenAPI description can be used to publish documentation or in another part of your API lifecycle where a limited part of your API is needed. Use a single source of truth in an OpenAPI description and allow the filtering to create the reduced version, rather than maintaining two API descriptions.

Filter any node (implicit target behavior)

You can also use the filter-out decorator on arbitrary properties that appear inside any OpenAPI object. For example, the following configuration looks for a property x-audience and removes any elements that have this property set to "Internal". Using this approach, you can remove specific parameters, responses, or endpoints from your OpenAPI description.

decorators:
  filter-out:
    property: x-audience
    value: Internal

In this mode, nodes without the x-audience property are preserved. This is useful when the property is applied broadly across different types of nodes in your API description.

Use the filter decorators so that you can maintain one complete source of truth, then prepare restricted documents as appropriate for downstream tools such as API reference documentation.

Resources

Decorator source