Copy page

OpenAPI

API Reference

The apis configuration setting in the Dev Portal Configuration file allows you to specify the OpenAPI document that you want to use to generate your API reference documentation.

There are multiple ways to reference an API file in the configuration including using a URL or a local file path. The OpenAPI document can be in either JSON or YAML format.

File Reference

You can reference a local OpenAPI document by setting the type to file and providing the path to the file.

zudoku.config.ts
const config = {
  // ...
  apis: {
    type: "file",
    input: "./openapi.json", // Supports JSON and YAML files (ex. openapi.yaml)
    path: "/api",
  },
  // ...
};

URL Reference

If your OpenAPI document is accessible elsewhere via URL you can use this configuration, changing the input value to the URL of your own OpenAPI document (you can use the Rick & Morty API document if you want to test and play around):

zudoku.config.ts
const config = {
  // ...
  apis: {
    type: "url",
    input: "https://rickandmorty.zuplo.io/openapi.json",
    path: "/api",
  },
  // ...
};

Versioning

File-based Versioning

When using type: "file", you can provide an array of file paths to create versioned API documentation. Version metadata is automatically extracted from each OpenAPI schema at build time:

zudoku.config.ts
const config = {
  apis: {
    type: "file",
    input: [
      // Order of the array determines the order of the versions
      "./openapi-v2.json",
      "./openapi-v1.json",
    ],
    path: "/api",
  },
};

If you need to override version metadata, you can specify it explicitly:

zudoku.config.ts
const config = {
  apis: {
    type: "file",
    input: [
      // Order of the array determines the order of the versions
      {
        path: "v2",
        label: "Version 2.0",
        input: "./openapi-v2.json",
      },
      {
        path: "v1",
        label: "Version 1.0",
        input: "./openapi-v1.json",
      },
    ],
    path: "/api",
  },
};

You can specify:

• input: Path to the OpenAPI document (required)
• path: Version identifier used in the URL path (e.g., /api/v2)
• label: Optional display name for the version selector

You can also mix strings and objects in the array - use strings for defaults and objects when you need to customize:

zudoku.config.ts
const config = {
  apis: {
    type: "file",
    input: [
      {
        path: "latest",
        label: "Latest (2.0)",
        input: "./openapi-v2.json",
      },
      "./openapi-v1.json", // Uses info.version from the document
    ],
    path: "/api",
  },
};

Splitting a Single Schema

If you have one schema containing multiple API versions (e.g. /v1/... and /v2/... paths), you can split it into separate versions by appending query parameters to the input path:

zudoku.config.ts
const config = {
  apis: {
    type: "file",
    input: ["openapi.json?prefix=/v2", "openapi.json?prefix=/v1"],
    path: "/api",
  },
};

The query parameters are passed to schema processors via the params argument, where you can filter the schema based on their values. See Using Query Parameters to Split Schemas for a full example.

URL-based Versioning

When using type: "url", you can provide an array of version configurations. Since URL-based schemas cannot be processed at build time, you must explicitly specify the version identifier and optional label:

zudoku.config.ts
const config = {
  apis: {
    type: "url",
    input: [
      {
        path: "v2",
        label: "Version 2.0",
        input: "https://api.example.com/openapi-v2.json",
      },
      {
        path: "v1",
        label: "Version 1.0",
        input: "https://api.example.com/openapi-v1.json",
      },
    ],
    path: "/api",
  },
};

Each URL version object requires:

• path: Version identifier used in the URL path (e.g., /api/v2)
• input: URL to the OpenAPI document
• label: Optional display name for the version selector (defaults to path if not provided)

Options

The options field allows you to customize the API reference behavior:

zudoku.config.ts
const config = {
  apis: {
    type: "file",
    input: "./openapi.json",
    path: "/api",
    options: {
      examplesLanguage: "shell", // Default language for code examples
      supportedLanguages: [
        { value: "shell", label: "cURL" },
        { value: "javascript", label: "JavaScript" },
      ],
      disablePlayground: false, // Disable the interactive API playground
      disableSidecar: false, // Disable the sidecar completely
      disableSecurity: true, // Disable security scheme display and playground auth (default)
      showVersionSelect: "if-available", // Control version selector visibility
      expandAllTags: true, // Control initial expanded state of tag categories
      showInfoPage: true, // Show API information page as the index route
      schemaDownload: {
        enabled: true, // Enable schema download button
        fileName: "schema", // Set name of the schema file when downloaded
      },
    },
  },
};

Available options:

• examplesLanguage: Set default language for code examples
• supportedLanguages: Array of language options for code examples. Each option has value (code identifier) and label (display name)
• disablePlayground: Disable the interactive API playground globally
• disableSidecar: Disable the sidecar panel completely
• disableSecurity: Disable OpenAPI security scheme display (auth badges on operations, security schemes section on the info page, and the Authorize dialog in the playground). Disabled by default (true). Set to false to enable security scheme support
• showVersionSelect: Control version selector visibility
  • "if-available": Show version selector only when multiple versions exist (default)
  • "always": Always show version selector (disabled if only one version)
  • "hide": Never show version selector
• expandAllTags: Control initial expanded state of tag categories (default: true)
• showInfoPage: Show the API information page as the index route (default: true). When disabled, navigating to the API root redirects to the first tag instead
• schemaDownload: Enable schema download functionality. When enabled, displays a button allowing users to download the OpenAPI schema, copy it to clipboard, or open in a new tab.
  • enabled: Enable or disable the schema download button
  • fileName: Set name of the schema file when downloaded (default: schema). Note: Do not include a file extension, as that is added automatically based on the input file type.
• transformExamples: Function to transform request/response examples before rendering. See Transforming Examples for detailed usage
• generateCodeSnippet: Function to generate custom code snippets for the API playground. See Advanced Configuration below

Default Options

Instead of setting options for each API individually, you can use defaults.apis to set global defaults that apply to all APIs:

zudoku.config.ts
const config = {
  defaults: {
    apis: {
      examplesLanguage: "shell", // Default language for code examples
      disablePlayground: false, // Disable the interactive API playground
      disableSidecar: false, // Disable the sidecar completely
      disableSecurity: true, // Disable security scheme display and playground auth (default)
      showVersionSelect: "if-available", // Control version selector visibility
      expandAllTags: false, // Control initial expanded state of tag categories
      showInfoPage: true, // Show API information page as the index route
      schemaDownload: {
        enabled: true, // Enable schema download button
        fileName: "schema", // Set name of the schema file when downloaded
      },
    },
  },
  apis: {
    type: "file",
    input: "./openapi.json",
    path: "/api",
  },
};

Individual API options will override these defaults when specified.

AI Assistants

The schema download dropdown includes AI assistant options (Claude, ChatGPT) by default. You can customize or disable these using the top-level aiAssistants configuration. See AI Assistants for full documentation.

Advanced Configuration

Custom Code Snippets

Use generateCodeSnippet to generate custom code snippets instead of the default HTTP examples. This is useful when you want to show SDK usage or language-specific implementations.

zudoku.config.tsx
const config: ZudokuConfig = {
  apis: {
    type: "file",
    input: "./openapi.json",
    path: "/api",
    options: {
      supportedLanguages: [
        { value: "js", label: "JavaScript" },
        { value: "python", label: "Python" },
      ],
      generateCodeSnippet: ({ selectedLang, selectedServer, operation, example }) => {
        if (operation.operationId === "createUser") {
          if (selectedLang === "js") {
            return `
import { Client } from "@mycompany/sdk";

const client = new Client({ baseUrl: "${selectedServer}" });
const user = await client.createUser(${JSON.stringify(example, null, 2)});
            `.trim();
          }
          if (selectedLang === "python") {
            return `
from mycompany import Client

client = Client(base_url="${selectedServer}")
user = client.create_user(${JSON.stringify(example)})
            `.trim();
          }
        }
        // Return false to use default snippet generation
        return false;
      },
    },
  },
};

The function receives:

• selectedLang: Currently selected language from supportedLanguages
• selectedServer: Currently selected server URL
• operation: The OpenAPI operation object
• example: The current request body example

Return a string with the custom snippet, or false to fall back to default generation.

Extensions

Dev Portal supports OpenAPI extensions (properties starting with x-) to customize behavior at different levels of your API documentation.

Operations

• x-zudoku-playground-enabled: Control playground visibility for an operation (default: true)
• x-explorer-enabled: Alias for x-zudoku-playground-enabled for compatibility Example:

Code
{
  "paths": {
    "/users": {
      "get": {
        "summary": "Get users",
        "x-zudoku-playground-enabled": false // Disable playground for this operation
      }
    }
  }
}

Tags

Extensions that can be applied to tag categories:

• x-zudoku-collapsed: Control initial collapsed state of a tag category (default: true)
• x-zudoku-collapsible: Control if a tag category can be collapsed (default: true)

Example:

Code
{
  "tags": [
    {
      "name": "Users",
      "x-zudoku-collapsed": false
    }
  ]
}

Tag Groups

Use x-tagGroups at the root of your OpenAPI document to group tags together in the navigation:

Code
x-tagGroups:
  - name: Shipment
    tags:
      - Packages
      - Parcels
      - Letters

Metadata

Your API reference page metadata is sourced directly from your OpenAPI spec. The info object is used set the corresponding tags in the page's head.

Metadata Property	OpenAPI Property	Comment
title	info.title	If metadata.title is set as a template string (ex. %s - My Company) it will be used
description	info.summary	info.summary is preferred as it is shorter and plaintext-only, but Dev Portal will fall back to the info.description if no summary is provided