Skip to main content

​
API Plugin

The API plugin enables automatic generation of API documentation from OpenAPI specifications and Kubernetes Custom Resource Definitions (CRDs).

​
Features

  • OpenAPI Support - Convert OpenAPI 2.0 (Swagger) and 3.0+ specs to documentation
  • CRD Documentation - Generate docs from Kubernetes CRD YAML files
  • Automatic Schema Conversion - Converts OpenAPI schemas to JSON Schema
  • Runtime Access - Access API specs and CRDs in your components

​
Configuration

Configure the API plugin in your doom.config.ts: 
import { defineConfig } from '@alauda/doom'

export default defineConfig({
  api: {
    // Paths to OpenAPI spec files
    openapis: [
      'specs/api-v1.yaml',
      'specs/api-v2.json'
    ],
    
    // Paths to CRD YAML files
    crds: [
      'crds/myresource.yaml'
    ],
    
    // External API references
    references: {
      'external-api': 'https://api.example.com/openapi.json'
    },
    
    // Path prefix for API routes
    pathPrefix: '/api-docs'
  }
})

​
OpenAPI Documentation

​
Supported Formats

The plugin supports multiple OpenAPI formats:
  • OpenAPI 3.1.x (native)
  • OpenAPI 3.0.x (converted to 3.1)
  • Swagger 2.0 (converted to OpenAPI 3.1)

​
Automatic Conversion

The plugin automatically handles format conversion:
packages/doom/src/plugins/api/index.ts:48-62
// Swagger 2.0 → OpenAPI 3.1
if ('swagger' in doc && doc.swagger === '2.0') {
  doc = (await convertObj(doc, {})).openapi
}

// OpenAPI 3.0 → OpenAPI 3.1
if ('openapi' in doc && doc.openapi.startsWith('3.0.')) {
  doc = openapiSchemaToJsonSchema(doc) as OpenAPIV3_1.Document
  doc.openapi = '3.1.0'
}

​
CRD Documentation

​
CRD Structure

The plugin expects standard Kubernetes CRD format: 
apiVersion: apiextensions.k8s.io/v1
kind: CustomResourceDefinition
metadata:
  name: myresources.example.com
spec:
  group: example.com
  names:
    kind: MyResource
    plural: myresources
    singular: myresource
  scope: Namespaced
  versions:
    - name: v1
      served: true
      storage: true
      schema:
        openAPIV3Schema:
          type: object
          properties:
            spec:
              type: object
              # ... schema definition

​
TypeScript Types

The plugin provides TypeScript types for CRDs:
packages/doom/src/plugins/api/types.ts:11-38
export interface CustomResourceDefinition {
  apiVersion: string
  kind: 'CustomResourceDefinition'
  metadata: {
    annotations: Record<string, string>
    name: string
  }
  spec: {
    group: string
    names: {
      kind: string
      listKind: string
      plural: string
      singular: string
    }
    scope: 'Namespaced' | 'Cluster'
    versions: CustomResourceDefinitionVersion[]
  }
}

​
Runtime Access

Access API specs and CRDs in your components: 
import crdsMap from 'doom-@api-crdsMap'
import openapisMap from 'doom-@api-openapisMap'
import virtual from 'doom-@api-virtual'

// Access CRDs
const myCRD = crdsMap['myresource']

// Access OpenAPI specs
const myAPI = openapisMap['api-v1']

// Access configuration
const { references, pathPrefix } = virtual

​
Plugin Options

packages/doom/src/plugins/api/types.ts:3-9
export interface ApiPluginOptions {
  localBasePath: string      // Base path for resolving local files
  crds?: string[]            // Glob patterns for CRD files
  openapis?: string[]        // Glob patterns for OpenAPI files
  references?: Record<string, string>  // External API references
  pathPrefix?: string        // URL path prefix for API docs
}

​
Example Usage

Create an API documentation page:
docs/api/my-api.mdx
---
title: My API Reference
---

import { ApiReference } from '@alauda/doom/runtime'
import spec from 'doom-@api-openapisMap'

# My API Reference

<ApiReference spec={spec['my-api']} />

​
Best Practices

  1. Organize by Version - Keep different API versions in separate files
  2. Use Glob Patterns - Leverage glob patterns to include multiple specs
  3. External References - Use the references option for external APIs
  4. Validate Specs - Ensure OpenAPI specs are valid before building
  5. Document Schemas - Add descriptions to all schema properties

Build docs developers (and LLMs) love

Get started for freeTalk to us