lokicms-plugin-api-docs

REST API documentation generator for LokiCMS with OpenAPI 3.0, Markdown, and TypeScript support.

Features

• Complete REST API Documentation: Documents all LokiCMS REST endpoints (auth, entries, content-types, media, etc.)
• Multiple Output Formats: JSON, Markdown, OpenAPI 3.0, TypeScript interfaces
• Content Type Schemas: Generates documentation for registered content types
• Filtering: Filter endpoints by tag, HTTP method, or search term
• 5 MCP Tools: Full control via Model Context Protocol

Installation

npm install lokicms-plugin-api-docs

Usage

import apiDocsPlugin from 'lokicms-plugin-api-docs';

const cms = createLokiCMS({
  plugins: [apiDocsPlugin],
  apiDocs: {
    title: 'My API',
    version: '1.0.0',
    description: 'REST API documentation for my LokiCMS project',
    baseUrl: 'https://api.example.com',
    includeExamples: true,
  },
});

MCP Tools

| Tool | Description | |------|-------------| | docs_generate | Generate complete REST API documentation | | docs_endpoints | List endpoints with filtering by tag, method, or search | | docs_tags | List all API categories/tags | | docs_content_types | Document content types and their field schemas | | docs_export | Export documentation to a file |

docs_generate

Generate complete REST API documentation.

{
  "format": "openapi",
  "tags": ["Authentication", "Entries"],
  "includeContentTypes": true,
  "includeExamples": true,
  "baseUrl": "https://api.example.com"
}

Output formats:

• json - Raw structured JSON
• markdown - Human-readable documentation
• openapi - OpenAPI 3.0 specification
• typescript - TypeScript interfaces

docs_endpoints

List REST API endpoints with filtering.

{
  "format": "json",
  "tag": "Entries",
  "method": "GET",
  "search": "publish"
}

Response:

{
  "success": true,
  "count": 12,
  "endpoints": [
    {
      "method": "GET",
      "path": "/api/entries",
      "summary": "List entries",
      "requiresAuth": false,
      "tags": ["Entries"]
    }
  ]
}

docs_tags

List all available API tags/categories.

{
  "includeEndpointCounts": true
}

Response:

{
  "success": true,
  "tags": [
    { "tag": "Authentication", "endpointCount": 8 },
    { "tag": "Entries", "endpointCount": 12 },
    { "tag": "Media", "endpointCount": 8 }
  ]
}

docs_content_types

Document content types and their schemas.

{
  "format": "typescript",
  "filter": "product"
}

docs_export

Export documentation to a file.

{
  "format": "openapi",
  "outputPath": "./docs/openapi.json",
  "baseUrl": "https://api.example.com"
}

API Coverage

This plugin documents all LokiCMS REST API endpoints:

| Category | Endpoints | |----------|-----------| | Authentication | Login, register, refresh token, API keys | | Content Types | CRUD operations, field management | | Entries | CRUD, publish/unpublish, archive, terms | | Search | Global search, suggestions, content type search | | Media | Upload, list, update, delete, serve files | | Taxonomies | Category/tag system management | | Terms | Individual taxonomy term management | | Users | User account management | | GraphQL | GraphQL endpoint documentation | | Utility | Health check, plugin list |

Output Examples

OpenAPI 3.0

{
  "openapi": "3.0.0",
  "info": {
    "title": "LokiCMS REST API",
    "version": "1.0.0"
  },
  "paths": {
    "/api/auth/login": {
      "post": {
        "summary": "Login with credentials",
        "tags": ["Authentication"],
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "email": { "type": "string", "format": "email" },
                  "password": { "type": "string" }
                }
              }
            }
          }
        }
      }
    },
    "/api/entries": {
      "get": {
        "summary": "List entries",
        "parameters": [
          { "name": "contentType", "in": "query" },
          { "name": "status", "in": "query" }
        ]
      }
    }
  },
  "components": {
    "securitySchemes": {
      "bearerAuth": { "type": "http", "scheme": "bearer" },
      "apiKey": { "type": "apiKey", "in": "header", "name": "X-API-Key" }
    }
  }
}

Markdown

# LokiCMS REST API

## Authentication

### `POST` /api/auth/login
Login with credentials. Returns JWT tokens.

**Request Body:**
| Field | Type | Required | Description |
|-------|------|----------|-------------|
| email | string | Yes | User email |
| password | string | Yes | Password |

### `GET` /api/auth/me
Get current user profile and permissions.

## Entries

### `GET` /api/entries
List entries with filtering and pagination.
...

TypeScript

/**
 * Entry content object
 */
export interface ProductEntry {
  id: string;
  contentTypeId: string;
  contentTypeSlug: string;
  slug: string;
  title: string;
  status: 'draft' | 'published' | 'scheduled' | 'archived';
  data: {
    name: string;
    price: number;
    description?: string;
  };
  createdAt: number;
  updatedAt: number;
}

Programmatic Usage

import {
  getDocGenerator,
  formatAsOpenApi,
  generateTypeScript,
} from 'lokicms-plugin-api-docs';

// Get the documentation generator
const docGen = getDocGenerator();

// Generate documentation
const docs = await docGen.generate({
  includeContentTypes: true,
  includeExamples: true,
});

// Format as OpenAPI
const openApiSpec = formatAsOpenApi(docs, {
  baseUrl: 'https://api.example.com',
});

// Generate TypeScript interfaces
const tsOutput = generateTypeScript(docs);
console.log(tsOutput.code);

// Get endpoints by tag
const authEndpoints = docGen.getEndpoints('Authentication');

// Get all tags
const tags = docGen.getTags();

Configuration

interface ApiDocsConfig {
  /** API title for documentation */
  title?: string;
  /** API version */
  version?: string;
  /** API description */
  description?: string;
  /** Base URL for endpoints */
  baseUrl?: string;
  /** Include example values in documentation */
  includeExamples?: boolean;
  /** Default output directory for exports */
  outputDir?: string;
}

Frontend Integration

Use the generated OpenAPI spec or TypeScript types for frontend development:

1. Export OpenAPI spec:

{ "format": "openapi", "outputPath": "./docs/api.json" }

2. Generate TypeScript client:

npx openapi-typescript ./docs/api.json -o ./src/api-types.ts

3. Use with fetch/axios:

import type { ProductEntry } from './api-types';

const response = await fetch('https://api.example.com/api/entries?contentType=product');
const data = await response.json();
const products: ProductEntry[] = data.entries;

License

MIT