Zudoku Configuration API

openapi: 3.2.0
info:
  title: Zudoku API References Configuration API
  description: Zudoku is an open-source, developer-first API documentation framework built by Zuplo.
  version: 1.0.0
  contact:
    name: Zuplo
    url: https://zudoku.dev
  license:
    name: MIT
    url: https://github.com/zuplo/zudoku/blob/main/LICENSE
servers:
- url: https://zudoku.dev
  description: Zudoku documentation site
tags:
- name: Configuration
  description: Top-level Zudoku configuration management.
paths:
  /config:
    get:
      operationId: getConfiguration
      summary: Retrieve Zudoku Configuration
      description: Represents the top-level Zudoku configuration object defined in zudoku.config.ts. This configuration drives all documentation generation, theming, navigation, authentication, and API reference rendering.
      tags:
      - Configuration
      responses:
        '200':
          description: The full Zudoku configuration object.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ZudokuConfig'
components:
  schemas:
    Metadata:
      type: object
      description: Site metadata for SEO and social sharing.
      properties:
        title:
          type: string
          description: Site title.
        description:
          type: string
          description: Site description.
        favicon:
          type: string
          description: Path to favicon.
    ThemeConfig:
      type: object
      description: Theme and branding configuration for customizing the look and feel of the generated documentation portal.
      properties:
        light:
          $ref: '#/components/schemas/ThemeColors'
        dark:
          $ref: '#/components/schemas/ThemeColors'
        fonts:
          type: object
          properties:
            heading:
              type: string
            body:
              type: string
            code:
              type: string
    Plugin:
      type: object
      description: A Zudoku plugin configuration. Plugins extend the platform with additional functionality such as search, analytics, and custom pages.
      properties:
        name:
          type: string
          description: Plugin name identifier.
        config:
          type: object
          description: Plugin-specific configuration options.
          additionalProperties: true
    AuthenticationConfig:
      type: object
      description: Authentication configuration supporting OpenID Connect, OAuth2, and custom authentication providers for the documentation portal and API playground.
      properties:
        type:
          type: string
          enum:
          - openid
          - oauth2
          - custom
          description: The authentication provider type.
        clientId:
          type: string
          description: OAuth2/OIDC client identifier.
        issuer:
          type: string
          description: OIDC issuer URL.
        scopes:
          type: array
          items:
            type: string
          description: Requested OAuth2 scopes.
        redirectUri:
          type: string
          description: OAuth2 redirect URI after authentication.
    ThemeColors:
      type: object
      description: Color palette for a theme mode.
      properties:
        primary:
          type: string
          description: Primary brand color.
        background:
          type: string
          description: Background color.
        border:
          type: string
          description: Border color.
    ZudokuConfig:
      type: object
      description: The top-level Zudoku configuration object, typically defined in zudoku.config.ts or zudoku.config.tsx.
      properties:
        topNavigation:
          type: array
          description: Top navigation bar items.
          items:
            $ref: '#/components/schemas/NavigationItem'
        sidebar:
          type: object
          description: Sidebar navigation grouped by section.
          additionalProperties:
            type: array
            items:
              $ref: '#/components/schemas/SidebarItem'
        apis:
          type: array
          description: API reference configurations pointing to OpenAPI documents.
          items:
            $ref: '#/components/schemas/ApiReference'
        docs:
          type: array
          description: MDX documentation page configurations.
          items:
            $ref: '#/components/schemas/DocConfig'
        authentication:
          $ref: '#/components/schemas/AuthenticationConfig'
        theme:
          $ref: '#/components/schemas/ThemeConfig'
        metadata:
          $ref: '#/components/schemas/Metadata'
        plugins:
          type: array
          description: Registered plugins.
          items:
            $ref: '#/components/schemas/Plugin'
        redirects:
          type: array
          description: URL redirect rules.
          items:
            $ref: '#/components/schemas/Redirect'
        basePath:
          type: string
          description: Base path for the documentation site.
        page:
          type: object
          description: Page-level configuration such as logo and banner.
          properties:
            logo:
              type: object
              properties:
                src:
                  type: object
                  properties:
                    light:
                      type: string
                    dark:
                      type: string
            banner:
              type: object
              properties:
                message:
                  type: string
                color:
                  type: string
    Redirect:
      type: object
      description: A URL redirect rule.
      properties:
        from:
          type: string
          description: Source path pattern.
        to:
          type: string
          description: Target path.
    ApiReference:
      type: object
      description: Configuration for an API reference that points to an OpenAPI schema document. Supports file-based and URL-based references, versioning, and server URL overrides.
      required:
      - type
      - input
      properties:
        type:
          type: string
          enum:
          - file
          - url
          description: How the OpenAPI document is loaded. 'file' for local filesystem, 'url' for remote HTTP.
        input:
          oneOf:
          - type: string
            description: Path or URL to the OpenAPI document.
          - type: array
            items:
              type: string
            description: Array of file paths for versioned documentation.
        navigationId:
          type: string
          description: Identifier used for sidebar navigation linking.
        label:
          type: string
          description: Display label for the API reference.
        serverUrl:
          type: string
          description: Override the server URL in the OpenAPI document.
    SidebarItem:
      type: object
      description: A sidebar navigation item which can be a page, link, or category.
      properties:
        type:
          type: string
          enum:
          - page
          - link
          - category
          description: The type of sidebar item.
        id:
          type: string
          description: Page identifier for internal pages.
        label:
          type: string
          description: Display text.
        link:
          type: string
          description: URL for external links.
        items:
          type: array
          description: Child items for category type.
          items:
            $ref: '#/components/schemas/SidebarItem'
    DocConfig:
      type: object
      description: Configuration for MDX-based documentation pages.
      properties:
        files:
          type: string
          description: Glob pattern for MDX files to include.
    NavigationItem:
      type: object
      description: A top navigation bar item.
      properties:
        id:
          type: string
          description: Unique identifier matching a sidebar or API section.
        label:
          type: string
          description: Display text for the navigation item.
        default:
          type: string
          description: Default path for this navigation section.