Copy page

OpenAPI

API Catalog

Applies to

Developer Portalthe documentation site for your API consumers

Hosting

Managed EdgeManaged DedicatedSelf-Hosted

If you're dealing with multiple APIs and multiple OpenAPI files, the API Catalog comes in handy. It creates an overview of all your APIs and lets you organize them into categories and tags.

Categories and Tags

Each entry in an API's categories array has two fields, label and tags, which serve different purposes:

• label is the primary grouping. The catalog page renders one filter chip per unique label, so this is what users click to narrow the list. An API can belong to multiple categories by adding multiple entries to the array.
• tags are secondary descriptors attached to that category. They do not get their own filter chip. Instead, they are matched against the search input and rendered as additional badges on the API card (alongside the label). Use them for finer-grained keywords that should help users discover an API without cluttering the top-level filters.

For example, { label: "Payments", tags: ["billing", "subscriptions"] } puts the API under the "Payments" filter chip and adds "billing" and "subscriptions" as searchable badges on its card.

Enable API Catalog

To enable the API Catalog, add a catalogs object to your Dev Portal configuration file.

zudoku.config.ts
const config = {
  // ...
  catalogs: {
    path: "/catalog",
    label: "API Catalog",
  },
  // ...
};

You can then add your APIs to the catalog by adding the categories property to your API configuration.

zudoku.config.ts
const config = {
  catalogs: {
    path: "/catalog",
    label: "API Catalog",
  },
  apis: [
    {
      type: "file",
      input: "./operational.json",
      path: "/catalog/api-operational", // Must be under /catalog/
      categories: [{ label: "General", tags: ["Operational"] }],
    },
    {
      type: "file",
      input: "./enduser.json",
      path: "/catalog/api-enduser", // Must be under /catalog/
      categories: [{ label: "General", tags: ["End-User"] }],
    },
    {
      type: "file",
      input: "./openapi.json",
      path: "/catalog/api-auth", // Must be under /catalog/
      categories: [{ label: "Other", tags: ["Authentication"] }],
    },
  ],
};

To add the catalog to your navigation, use a link item:

zudoku.config.ts
const config = {
  navigation: [
    {
      type: "link",
      label: "API Catalog",
      to: "/catalog",
      icon: "square-library",
    },
  ],
  // ... catalogs and apis config
};

Advanced Configuration

Filtering catalog items

You can filter which APIs are shown in the catalog by using the filterItems property. The function receives the items and the catalog context (including auth) as arguments. Each item has a categories array where each category has a label and tags.

zudoku.config.ts
const config = {
  catalogs: {
    path: "/catalog",
    label: "API Catalog",
    filterItems: (items, { auth }) => {
      return items.filter((item) =>
        item.categories?.some((category) => category.tags?.includes("public")),
      );
    },
  },
};

Standalone APIs (without catalog)

APIs that are not part of a catalog can use any path and will appear as standalone API reference pages. These APIs don't need categories and their paths don't need to be nested under a catalog.

zudoku.config.ts
const config = {
  apis: [
    {
      type: "file",
      input: "./openapi.json",
      path: "/api", // standalone, not under a catalog
    },
  ],
  navigation: [
    {
      type: "link",
      label: "API Reference",
      to: "/api",
    },
  ],
};

See the API Reference page for full details on configuring individual APIs, including versioning and customization options.