Organize your content into a catalog that users can filter and search. You can configure multiple catalogs and set the link text, description, and filters.
| Option | Type | Description |
|---|---|---|
| catalogClassic | Map[string, Catalog Classic] | REQUIRED. Map of strings allows for the definition of multiple catalogs. Strings represent catalog only in configuration file - they do not appear in published project. Example: internal-apis |
| Option | Type | Description |
|---|---|---|
| title | string | REQUIRED. Heading and page title in published project. Example: Acme API catalog |
| titleTranslationKey | string | Page title key used for localization. |
| icon | string | A Font Awesome or relative path to icon image file. Font Awesome icons can be prefixed with type: duotone, solid, regular or brands. Example: book, duotone book, ./images/config-icon.svg. |
| description | string | REQUIRED. Description of the page that appears in published project. Example: Discover how our APIs can support your business. |
| descriptionTranslationKey | string | Page description key used for localization. |
| slug | string | REQUIRED. What you want the path segment of the URL for the catalog to be. Must have a leading and trailing slash. Must match the page or href value for the item on the navbar. Example: /catalog/ |
| filters | [Filter] | List of filter configurations which allows for quicker discovery. See metadata for more information on how to categorize content for filtering. |
| filterValuesCasing | string | Transform casing of filter values. Possible values: lowercase, uppercase, sentence, original. Default: original. |
| separateVersions | boolean | Separates content with multiple versions into their own distinct catalog items. Default: false. |
| groupByFirstFilter | boolean | Groups items by the first filter they belong to. Default: false. |
| items | [Item] | List of item configurations which determines what content is included in the catalog. |
| Option | Type | Description |
|---|---|---|
| title | string | REQUIRED. Title of the filter to display above the filter options. |
| titleTranslationKey | string | Filter title key used for localization. |
| property | string | REQUIRED. Indicates the field from x-metadata (OpenAPI extension) or metadata (in front matter) to use for the filter. |
| valuesMapping | string | Map filter values to different values. Useful for mapping legacy metadata values to new values. Default value: {}. |
| missingCategoryName | string | If an API does not have x-metadata and the corresponding filter property defined, then the API belongs to this missing category. Default value: Other. |
| missingCategoryNameTranslationKey | string | Missing category name key used for localization. |
| type | string | Type of the filter in the UI. Possible values: checkboxes or select. |
| parentFilter | string | Property name of the filter to use as a parent. The current filter becomes active only after the parent filter is selected. Useful with select filter as a parent. |
| options | [string] | Static list of filter options to include for this filter. If not provided, the filter options are dynamically generated from the metadata values in the catalog. |
| Option | Type | Description |
|---|---|---|
| directory | string | REQUIRED. Path to the directory where the API descriptions or content files included in catalog are stored. Example: ./. |
| flatten | boolean | Recurses all included sub-directories for files that match the target types and includes them in the catalog. When false, only the top-level items that match the target types are in the catalog as well as the first file from every subdirectory. Default: false. |
| includeByMetadata | Map[string, [string]] | Map of metadata properties to list of string values. Restricts what to include in the catalog. Example: {"type": ["openapi"]}. |
When users click an item in the catalog, the routing behavior depends on your sidebar configuration:
- With sidebars.yaml: The catalog routes to the first item defined in the corresponding
sidebars.yamlfile that links to that catalog item - Without sidebars.yaml: A sidebar is generated automatically from the files in the directory, and routing goes to the first file
This means clicking an OpenAPI document in the catalog may not navigate directly to the API reference documentation. Instead, it navigates to whatever appears first in your sidebar configuration, such as a home page or getting started guide.
To ensure users reach specific content when clicking catalog items, organize your sidebars.yaml files so the most important content appears first, or create dedicated landing pages that introduce each API.
If you want to only show the catalog to users that are members of particular teams, configure the rbac object in the redocly.yaml configuration file as follows:
rbac:
content:
/catalog/:
Developers: readSee rbac reference documentation for more options and examples.
The following example shows a complete catalog configuration including the required navbar configuration to make the catalog accessible.
First, organize your API description files into a logical folder structure:
my_project/
├──apis/
│ ├──payments/
│ │ ├──payments-api.yaml
│ │ └──webhooks-api.yaml
│ ├──users/
│ │ └──users-api.yaml
│ └──analytics/
│ ├──analytics-api.yaml
│ ├──index.md
│ └──getting-started.md
├──redocly.yaml
└──sidebars.yamlThen configure your catalog in redocly.yaml:
redocly.yaml
logo:
image: ./images/logo.svg
altText: Acme Corp
link: https://example.com
catalogClassic:
business:
title: API Catalog
description: 'Discover how our APIs can support your business'
slug: /apis/
items:
- directory: ./apis
flatten: true
includeByMetadata:
type: [openapi, graphql]
filters:
- title: Business Capability
property: capability
missingCategoryName: Other
type: select
- title: API Stage
property: tags
options: [beta, draft, stable]
type: checkboxes
- title: API Status
property: tags
options: [deprecated, active]
type: checkboxes
navbar:
items:
- page: /apis/
icon: ./images/api-icon.png
linkedSidebars:
- ./sidebars.yaml
- label: Documentation
href: https://redocly.com/docs/
external: trueThe following is a minimal catalog configuration:
redocly.yaml
catalogClassic:
simple-catalog:
title: API catalog
description: 'Browse our available APIs'
slug: /catalog/
items:
- directory: ./
flatten: true
includeByMetadata:
type: [openapi]The following is an example of a classic catalog that uses tags property from x-metadata defined in the API description files.
redocly.yaml
catalogClassic:
simple-catalog:
title: Simple API catalog
description: Discover how our APIs can support your business
slug: /apis/
filters:
- title: Content type
property: tags
options: [Books, Magazines]
type: select- Sidebars configuration - Configure sidebar navigation structure to control how catalog items route when clicked by users
- x-metadata extension - Add metadata to OpenAPI files that can be used as catalog filters and displayed in API documentation
- Hide info metadata - Exclude metadata from API reference documentation when you want cleaner, focused documentation presentation
- API Governance - Learn about API standards and governance practices for maintaining quality and consistency
- Configure scorecard - Set up scorecards to check APIs against standards and maintain quality metrics
- Metadata categorization - Use metadata to filter and organize APIs in the classic catalog for better content discovery
- Configure navbar - Follow steps to include your catalog link in the navigation bar for easy access