Skip to content
Last updated

catalogClassic

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.

Screenshot of a catalog

Options

OptionTypeDescription
catalogClassicMap of strings to Catalog ClassicREQUIRED. 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

Catalog object

OptionTypeDescription
titlestringREQUIRED. Heading and page title in published project. Example: Acme API catalog
titleTranslationKeystringPage title key used for localization.
descriptionstringREQUIRED. Description of the page that appears in published project. Example: Discover how our APIs can support your business.
descriptionTranslationKeystringPage description key used for localization.
slugstringREQUIRED. 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.
filterValuesCasingstringTransform casing of filter values. Possible values: lowercase, uppercase, sentence, original. Default: original.
separateVersionsbooleanSeparates content with multiple versions into their own distinct catalog items. Default: false.
groupByFirstFilterbooleanGroups 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.

Filter object

OptionTypeDescription
titlestringREQUIRED. Title of the filter to display above the filter options.
titleTranslationKeystringFilter title key used for localization.
propertystringREQUIRED. Indicates the field from x-metadata (OpenAPI extension) or metadata (in front matter) to use for the filter.
valuesMappingstringMap filter values to different values. Useful for mapping legacy metadata values to new values. Default value: {}.
missingCategoryNamestringIf an API does not have x-metadata and the corresponding filter property defined, then the API belongs to this missing category. Default value: Other.
missingCategoryNameTranslationKeystringMissing category name key used for localization.
typestringType of the filter in the UI. Possible values: checkboxes or select.
parentFilterstringProperty 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.

Item object

OptionTypeDescription
directorystringREQUIRED. Path to the directory where the API descriptions or content files included in catalog are stored. Example: ./.
flattenbooleanRecurses 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.
includeByMetadataMap of metadata properties to list of string valuesRestricts what to include in the catalog. Example: {"type": ["openapi"]}.

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: read

See rbac reference documentation for more options and examples.

Examples

Complete catalog setup

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.yaml

Then 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: true

Basic catalog configuration

The 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]

x-metadata filters in classic catalog

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
  • View the configuration options available for translating content in the localization reference documentation.
  • See the navbar configuration documentation to see the format for adding a link to your catalog to the navbar.
  • Use x-metadata to make your API descriptions filterable.

Resources

 
Next page