Last updated 9 months ago

Nesting and filters

API operations without an `x-filters` attribute will not be displayed when using this feature.

Purpose

Use nesting and filters to organize and filter the left navigation. It is intended for multiple levels of nesting to organize large APIs.

Usage

To utilize this feature, you will need to add x-nesting to the top-level of your API definition, and x-filters to each operation you wish to display in the docs.

Add x-nesting on the top-level (next to info) - it should be an array with strings, order defines the order of nesting:

openapi: 3.0.1
info:
  description: some description
  # ...
x-nesting:
  - Market
  - Product
  - Authorization
# ...

Then, on each operation add x-filters with corresponding filters - this should be an map from the nesting group name to a string value (value can be an array of strings):

x-filters:
  Authorization: Intranet
  Product: AuthServer
  Market: ["US Only", "Asia"]

Beware: if an operation doesn’t define at least one nesting key in x-filters a warning is printed and the operation is not included on the resulting page.

Supported since

These vendor extensions have been supported since: @redocly/api-reference@1.0.0-rc.1. To utilize this feature, update your library to rc.1 or later, and make the adjustments above related to defining x-nesting and x-filters.