API Documentation

Doom’s API plugin automatically generates beautiful, interactive API documentation from OpenAPI specifications and Kubernetes Custom Resource Definitions (CRDs). It provides a unified way to document REST APIs, Kubernetes resources, and custom APIs.

Overview

The API plugin supports:

OpenAPI 2.0 (Swagger) - Automatically converted to OpenAPI 3.1
OpenAPI 3.0 - Converted to OpenAPI 3.1 with JSON Schema
OpenAPI 3.1 - Native support
Kubernetes CRDs - Full support for Custom Resource Definitions

Configuration

Configure the API plugin in your doom.config.yml:

api:
  # Glob patterns for CRD YAML files
  crds:
    - docs/shared/crds/*.yaml
    - apis/crds/**/*.yaml
  
  # Glob patterns for OpenAPI spec files
  openapis:
    - docs/shared/openapis/*.json
    - docs/shared/openapis/*.yaml
  
  # Type reference mappings for cross-linking
  references:
    v1alpha1.MyResource: /apis/references/MyResource#v1alpha1.MyResource
    io.k8s.api.core.v1.Pod: https://kubernetes.io/docs/reference/kubernetes-api/workload-resources/pod-v1/
  
  # Path prefix for API routes (optional)
  pathPrefix: /apis

OpenAPI Documentation

Basic Setup

Place your OpenAPI spec files in your docs directory:

docs/
└── shared/
    └── openapis/
        ├── petstore.json
        └── users-api.yaml

Configure the paths in doom.config.yml:

api:
  openapis:
    - docs/shared/openapis/*.json
    - docs/shared/openapis/*.yaml

Create a page to display the API:

---
title: Pet Store API
---

# Pet Store API

<OpenAPI spec="petstore" />

Supported Formats

The plugin automatically handles format conversion:

Swagger 2.0

Automatically converted to OpenAPI 3.1 using swagger2openapi

{
  "swagger": "2.0",
  "info": {
    "title": "My API",
    "version": "1.0.0"
  }
}

OpenAPI 3.0

Converted to OpenAPI 3.1 with proper JSON Schema support

openapi: 3.0.3
info:
  title: My API
  version: 1.0.0

OpenAPI 3.1

Used directly with full JSON Schema support

openapi: 3.1.0
info:
  title: My API
  version: 1.0.0

Example OpenAPI Spec

{
  "openapi": "3.1.0",
  "info": {
    "title": "User Management API",
    "version": "1.0.0",
    "description": "API for managing users"
  },
  "servers": [
    {
      "url": "https://api.example.com/v1"
    }
  ],
  "paths": {
    "/users": {
      "get": {
        "summary": "List users",
        "operationId": "listUsers",
        "parameters": [
          {
            "name": "limit",
            "in": "query",
            "schema": {
              "type": "integer",
              "default": 10
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Success",
            "content": {
              "application/json": {
                "schema": {
                  "type": "array",
                  "items": {
                    "$ref": "#/components/schemas/User"
                  }
                }
              }
            }
          }
        }
      }
    }
  },
  "components": {
    "schemas": {
      "User": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string"
          },
          "name": {
            "type": "string"
          },
          "email": {
            "type": "string",
            "format": "email"
          }
        },
        "required": ["id", "name", "email"]
      }
    }
  }
}

Kubernetes CRD Documentation

Basic Setup

Place your CRD YAML files in your docs directory:

docs/
└── shared/
    └── crds/
        ├── application.yaml
        └── deployment.yaml

Configure the paths:

api:
  crds:
    - docs/shared/crds/*.yaml

Create a page to display the CRD:

---
title: Application CRD
---

# Application Resource

<CRD spec="applications.app.k8s.io" version="v1beta1" />

Example CRD

apiVersion: apiextensions.k8s.io/v1
kind: CustomResourceDefinition
metadata:
  name: applications.app.k8s.io
  annotations:
    description: "Application resource for deploying apps"
spec:
  group: app.k8s.io
  names:
    kind: Application
    listKind: ApplicationList
    plural: applications
    singular: application
  scope: Namespaced
  versions:
    - name: v1beta1
      served: true
      storage: true
      schema:
        openAPIV3Schema:
          type: object
          properties:
            spec:
              type: object
              properties:
                replicas:
                  type: integer
                  description: Number of desired replicas
                  minimum: 0
                  default: 1
                image:
                  type: string
                  description: Container image to deploy
                  pattern: '^[a-z0-9.-]+/[a-z0-9.-]+:[a-z0-9.-]+$'
                env:
                  type: array
                  description: Environment variables
                  items:
                    type: object
                    properties:
                      name:
                        type: string
                      value:
                        type: string
                    required:
                      - name
                      - value
              required:
                - image
            status:
              type: object
              properties:
                conditions:
                  type: array
                  items:
                    type: object
                    properties:
                      type:
                        type: string
                      status:
                        type: string
                      reason:
                        type: string
                      message:
                        type: string

Type References

The references configuration allows you to create cross-links between types:

api:
  references:
    # Internal references
    v1alpha1.Application: /apis/references/Application#v1alpha1.Application
    v1alpha1.Database: /apis/references/Database#v1alpha1.Database
    
    # External references (Kubernetes)
    io.k8s.api.core.v1.Pod: https://kubernetes.io/docs/reference/kubernetes-api/workload-resources/pod-v1/
    io.k8s.api.core.v1.ConfigMap: https://kubernetes.io/docs/reference/kubernetes-api/config-and-storage-resources/config-map-v1/
    io.k8s.api.apps.v1.Deployment: https://kubernetes.io/docs/reference/kubernetes-api/workload-resources/deployment-v1/
    io.k8s.apimachinery.pkg.apis.meta.v1.ObjectMeta: https://kubernetes.io/docs/reference/kubernetes-api/common-definitions/object-meta/

When these types are referenced in schemas, they become clickable links:

properties:
  metadata:
    # Links to Kubernetes ObjectMeta docs
    $ref: '#/components/schemas/io.k8s.apimachinery.pkg.apis.meta.v1.ObjectMeta'
  deployment:
    # Links to your internal Deployment docs
    $ref: '#/components/schemas/v1alpha1.Deployment'

Components

OpenAPI Component

Display OpenAPI documentation:

<OpenAPI 
  spec="api-name" 
  operation="operationId" 
  method="GET"
  path="/users"
/>

spec

string

required

Name of the OpenAPI spec file (without extension)

operation

string

Specific operation ID to display

method

string

HTTP method to filter (GET, POST, PUT, DELETE, etc.)

path

string

API path to display

CRD Component

Display CRD documentation:

<CRD 
  spec="resource-name" 
  version="v1alpha1"
  kind="Application"
/>

spec

string

required

CRD name (e.g., “applications.app.k8s.io”)

version

string

Specific version to display

kind

string

Resource kind

Plugin Options

When using the API plugin programmatically:

import { apiPlugin } from '@alauda/doom'
import { defineConfig } from '@rspress/core'

export default defineConfig({
  plugins: [
    apiPlugin({
      localBasePath: '/path/to/docs',
    })
  ],
  api: {
    crds: ['docs/crds/*.yaml'],
    openapis: ['docs/openapis/*.json'],
    references: {
      'v1alpha1.MyType': '/apis/my-type'
    },
    pathPrefix: '/apis'
  }
})

localBasePath

string

required

Base path for resolving spec files

Virtual Modules

The plugin creates virtual modules for runtime access:

// Access CRDs map
import crdsMap from 'doom-@api-crdsMap'

// Access OpenAPI specs map
import openapisMap from 'doom-@api-openapisMap'

// Access configuration
import virtual from 'doom-@api-virtual'
console.log(virtual.references)
console.log(virtual.pathPrefix)

Advanced Usage

Multiple API Versions

Document multiple versions of the same API:

api:
  openapis:
    - docs/apis/v1/*.json
    - docs/apis/v2/*.json

# API v1
<OpenAPI spec="users-v1" />

# API v2
<OpenAPI spec="users-v2" />

Combining CRDs and OpenAPI

Document both Kubernetes resources and REST APIs:

---
title: Complete API Reference
---

# Kubernetes Resources

## Application CRD
<CRD spec="applications.app.k8s.io" />

## Database CRD
<CRD spec="databases.db.example.com" />

# REST APIs

## Management API
<OpenAPI spec="management-api" />

## Webhook API
<OpenAPI spec="webhook-api" />

External Schema References

Reference external schemas:

{
  "components": {
    "schemas": {
      "User": {
        "type": "object",
        "properties": {
          "address": {
            "$ref": "https://example.com/schemas/address.json"
          }
        }
      }
    }
  }
}

Best Practices

Keep Specs Updated

Regenerate OpenAPI specs and CRDs from source code regularly to keep docs in sync.

Add Descriptions

Include detailed descriptions in your schemas - they become part of the documentation.

Use Examples

Add example values in your OpenAPI specs to help users understand usage.

Version Your APIs

Maintain documentation for multiple API versions to support users on older versions.

Troubleshooting

Spec Not Found

If specs aren’t loading:

Solution

Verify the glob patterns match your file locations
Check file permissions (files must be readable)
Ensure files are valid JSON/YAML
Look for console errors during build

Invalid OpenAPI Format

For OpenAPI validation errors:

Solution

Validate your spec using an online validator
Check that required fields (info, openapi) are present
Ensure schema references ($ref) are valid
Use the correct OpenAPI version format

Missing CRD Versions

If CRD versions don’t appear:

Solution

Verify the CRD has a spec.versions array
Check that versions have schema.openAPIV3Schema
Ensure at least one version has served: true
Validate the CRD YAML syntax

Auto Sidebar

Organize API docs in your navigation automatically

Translation

Translate API documentation to multiple languages

Get Started

Core Concepts

Features

Guides

API Documentation

API Documentation

Overview

Configuration

OpenAPI Documentation

Basic Setup

Supported Formats

Example OpenAPI Spec

Kubernetes CRD Documentation

Basic Setup

Example CRD

Type References

Components

OpenAPI Component

CRD Component

Plugin Options

Virtual Modules

Advanced Usage

Multiple API Versions

Combining CRDs and OpenAPI

External Schema References

Best Practices

Keep Specs Updated

Add Descriptions

Use Examples

Version Your APIs

Troubleshooting

Spec Not Found

Invalid OpenAPI Format

Missing CRD Versions

Auto Sidebar

Translation

Build docs developers (and LLMs) love

Get Started

Core Concepts

Features

Guides

​API Documentation

​Overview

​Configuration

​OpenAPI Documentation

​Basic Setup

​Supported Formats

​Example OpenAPI Spec

​Kubernetes CRD Documentation

​Basic Setup

​Example CRD

​Type References

​Components

​OpenAPI Component

​CRD Component

​Plugin Options

​Virtual Modules

​Advanced Usage

​Multiple API Versions

​Combining CRDs and OpenAPI

​External Schema References

​Best Practices

Keep Specs Updated

Add Descriptions

Use Examples

Version Your APIs

​Troubleshooting

​Spec Not Found

​Invalid OpenAPI Format

​Missing CRD Versions

​Related Features

Auto Sidebar

Translation

Build docs developers (and LLMs) love

API Documentation

Overview

Configuration

OpenAPI Documentation

Basic Setup

Supported Formats

Example OpenAPI Spec

Kubernetes CRD Documentation

Basic Setup

Example CRD

Type References

Components

OpenAPI Component

CRD Component

Plugin Options

Virtual Modules

Advanced Usage

Multiple API Versions

Combining CRDs and OpenAPI

External Schema References

Best Practices

Troubleshooting

Spec Not Found

Invalid OpenAPI Format

Missing CRD Versions

Related Features