{"ast":{"$$mdtype":"Tag","name":"article","attributes":{},"children":[{"$$mdtype":"Tag","name":"Heading","attributes":{"level":1,"id":"filter-in","__idx":0},"children":["filter-in"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Preserves nodes that have specific ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["property"]}," set to the specific ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["value"]}," and removes others."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Applies to any node type defined by the ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["applyTo"]}," option."," ","If ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["applyTo"]}," is not set, applies to all nodes where the ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["property"]}," is declared."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["To find the exact type of a place in your API description, either:"]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Run the ",{"$$mdtype":"Tag","name":"Link","attributes":{"href":"/docs/cli/v2/commands/inspect-node-types"},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["inspect-node-types"]}," command"]}," with a pointer to that place."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Hover over it in the ",{"$$mdtype":"Tag","name":"Link","attributes":{"href":"https://redocly.com/docs/redocly-openapi/"},"children":["Redocly OpenAPI VS Code extension"]}," to see the same type hints."]}]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"api-design-principles","__idx":1},"children":["API design principles"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["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."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"configuration","__idx":2},"children":["Configuration"]},{"$$mdtype":"Tag","name":"div","attributes":{"className":"md-table-wrapper"},"children":[{"$$mdtype":"Tag","name":"table","attributes":{"className":"md"},"children":[{"$$mdtype":"Tag","name":"thead","attributes":{},"children":[{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Option"},"children":["Option"]},{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Type"},"children":["Type"]},{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Description"},"children":["Description"]}]}]},{"$$mdtype":"Tag","name":"tbody","attributes":{},"children":[{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":["property"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["string"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["REQUIRED."]}," The property name used for evaluation. Attempts to match the values."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":["value"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["[string]"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["REQUIRED."]}," List of values used for the matching."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":["matchStrategy"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["string"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Possible values: ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["all"]},", ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["any"]},". When ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["all"]},", must match all of the values supplied. When ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["any"]},", must match only one of the values supplied. Default value: ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["any"]},"."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":["applyTo"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["string"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Possible values: ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["PathItem"]},", ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["Operation"]},". When set, filtering is scoped to the specified target."]}]}]}]}]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"examples","__idx":3},"children":["Examples"]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"filter-operations-by-operationid","__idx":4},"children":["Filter operations by ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["operationId"]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Using the ",{"$$mdtype":"Tag","name":"Link","attributes":{"href":"https://github.com/Redocly/museum-openapi-example"},"children":["Museum API"]}," (v1.0.0), use the stats command to get a summary of its contents:"]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"bash","header":{"controls":{"copy":{}}},"source":"redocly stats openapi.yaml\n","lang":"bash"},"children":[]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["I'm interested in the paths and operations in particular:"]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Path Items: 5"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Operations: 8"]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["To restrict an OpenAPI description to only a few endpoints, this example uses ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["operationId"]}," with a list of permitted values. To configure this, add the following to ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["redocly.yaml"]},":"]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"yaml","header":{"controls":{"copy":{}}},"source":"apis:\n  filter:\n    root: openapi.yaml\n    decorators:\n      filter-in:\n        applyTo: Operation\n        property: operationId\n        value: [createSpecialEvent, listSpecialEvents]\n","lang":"yaml"},"children":[]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["To apply the decorator, use the ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["bundle"]}," command:"]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"bash","header":{"controls":{"copy":{}}},"source":"redocly bundle filter -o museum-events.yaml\n","lang":"bash"},"children":[]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Looking through the resulting file, only the named operations are listed in the ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["paths"]}," section, and running the ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["stats"]}," command again shows that the filtered API description contains:"]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Path Items: 1"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Operations: 2"]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["This approach allows you to publish sections of your API, without needing to share the entire thing with every consumer, or maintain multiple API descriptions for those different audiences."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"filter-operations-by-a-custom-property","__idx":5},"children":["Filter operations by a custom property"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["To keep only the operations marked for a public audience using a custom extension:"]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"yaml","header":{"controls":{"copy":{}}},"source":"decorators:\n  filter-in:\n    applyTo: Operation\n    property: x-audience\n    value: [Public, Partner]\n","lang":"yaml"},"children":[]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Operations without the ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["x-audience"]}," property are removed, so only explicitly marked operations remain."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"filter-any-node-implicit-target-behavior","__idx":6},"children":["Filter any node (implicit target behavior)"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["You can also use ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["filter-in"]}," without ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["applyTo"]}," to filter on other elements, such as parameters, responses, or other OpenAPI items."," ","The example ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["redocly.yaml"]}," shown below includes everything from the OpenAPI description that has an ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["x-audience"]}," property set to either \"Public\" or \"Partner\":"]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"yaml","header":{"controls":{"copy":{}}},"source":"decorators:\n  filter-in:\n    property: x-audience\n    value: [Public, Partner]\n","lang":"yaml"},"children":[]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["In this mode, nodes without the ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["x-audience"]}," property are preserved."," ","This is useful when the property is applied broadly across different types of nodes in your API description."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Use the filter decorators so that you can maintain one complete source of truth in OpenAPI format, then prepare restricted documents as appropriate for downstream tools such as API reference documentation."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"related-decorators","__idx":7},"children":["Related decorators"]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"Link","attributes":{"href":"/docs/cli/v2/decorators/filter-out"},"children":["filter-out"]}]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"Link","attributes":{"href":"/docs/cli/v2/decorators/remove-x-internal"},"children":["remove-x-internal"]}]}]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"resources","__idx":8},"children":["Resources"]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"Link","attributes":{"href":"https://github.com/Redocly/redocly-cli/blob/main/packages/core/src/decorators/common/filters/filter-in.ts"},"children":["Decorator source"]}]}]}]},"frontmatter":{},"tagList":[],"title":"filter-in","lastModified":"2026-09-08T11:53:22.000Z"}