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. This specification describes the configuration interface and internal structure used by the Zudoku platform to generate interactive API documentation from OpenAPI schemas. Zudoku does not expose a traditional REST API; instead, it uses a file-based configuration model (zudoku.config.ts or zudoku.config.tsx) to define API references, navigation, authentication, theming, and plugin integrations. This OpenAPI specification documents the logical configuration resources and their schemas for interoperability and catalog purposes.
  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:
    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
    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.
    DocConfig:
      type: object
      description: Configuration for MDX-based documentation pages.
      properties:
        files:
          type: string
          description: Glob pattern for MDX files to include.
    Redirect:
      type: object
      description: A URL redirect rule.
      properties:
        from:
          type: string
          description: Source path pattern.
        to:
          type: string
          description: Target path.
    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
    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.
    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.
    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.
    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
    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.
    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'