lokicms-plugin-api-docs 1.0.0 → 1.1.0

package/README.md

@@ -1,12 +1,13 @@
 # lokicms-plugin-api-docs
 
-API documentation generator for LokiCMS with OpenAPI, Markdown, and TypeScript output support.
+REST API documentation generator for LokiCMS with OpenAPI 3.0, Markdown, and TypeScript support.
 
 ## Features
 
-- **Runtime Introspection**: Automatically discovers registered MCP tools and content types
+- **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
-- **Zod Schema Conversion**: Converts Zod schemas to JSON Schema for documentation
+- **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
@@ -25,8 +26,8 @@ const cms = createLokiCMS({
   apiDocs: {
     title: 'My API',
     version: '1.0.0',
-    description: 'API documentation for my LokiCMS project',
-    baseUrl: 'http://localhost:3000',
+    description: 'REST API documentation for my LokiCMS project',
+    baseUrl: 'https://api.example.com',
     includeExamples: true,
   },
 });
@@ -36,134 +37,220 @@ const cms = createLokiCMS({
 
 | Tool | Description |
 |------|-------------|
-| `docs_generate` | Generate complete API documentation in specified format |
-| `docs_tools` | List all available MCP tools with their schemas |
-| `docs_content_types` | Document all content types and their fields |
+| `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_endpoints` | Generate REST-like endpoint documentation |
 
 ### docs_generate
 
-Generate complete API documentation.
+Generate complete REST API documentation.
 
 ```json
 {
   "format": "openapi",
-  "includeTools": true,
+  "tags": ["Authentication", "Entries"],
   "includeContentTypes": true,
   "includeExamples": true,
   "baseUrl": "https://api.example.com"
 }
 ```
 
-### docs_tools
+**Output formats:**
+- `json` - Raw structured JSON
+- `markdown` - Human-readable documentation
+- `openapi` - OpenAPI 3.0 specification
+- `typescript` - TypeScript interfaces
 
-List all available MCP tools.
+### docs_endpoints
+
+List REST API endpoints with filtering.
 
 ```json
 {
-  "format": "markdown",
-  "filter": "vault",
-  "includeExamples": true
+  "format": "json",
+  "tag": "Entries",
+  "method": "GET",
+  "search": "publish"
 }
 ```
 
-### docs_content_types
-
-Document content types.
-
+**Response:**
 ```json
 {
-  "format": "typescript",
-  "filter": "product"
+  "success": true,
+  "count": 12,
+  "endpoints": [
+    {
+      "method": "GET",
+      "path": "/api/entries",
+      "summary": "List entries",
+      "requiresAuth": false,
+      "tags": ["Entries"]
+    }
+  ]
 }
 ```
 
-### docs_export
+### docs_tags
 
-Export documentation to a file.
+List all available API tags/categories.
 
 ```json
 {
-  "format": "openapi",
-  "outputPath": "./docs/api.json"
+  "includeEndpointCounts": true
 }
 ```
 
-### docs_endpoints
-
-Generate endpoint documentation.
-
+**Response:**
 ```json
 {
-  "format": "markdown",
-  "groupByTag": true
+  "success": true,
+  "tags": [
+    { "tag": "Authentication", "endpointCount": 8 },
+    { "tag": "Entries", "endpointCount": 12 },
+    { "tag": "Media", "endpointCount": 8 }
+  ]
 }
 ```
 
-## Output Formats
+### docs_content_types
 
-### JSON
+Document content types and their schemas.
 
-Raw structured JSON output with all documentation data.
+```json
+{
+  "format": "typescript",
+  "filter": "product"
+}
+```
 
-### Markdown
+### docs_export
 
-Human-readable documentation with tables and formatting:
+Export documentation to a file.
 
-```markdown
-# My API Documentation
+```json
+{
+  "format": "openapi",
+  "outputPath": "./docs/openapi.json",
+  "baseUrl": "https://api.example.com"
+}
+```
 
-## MCP Tools
+## API Coverage
 
-### vault_create
-Create a new credential
+This plugin documents all LokiCMS REST API endpoints:
 
-**Parameters:**
-| Name | Type | Required | Description |
-|------|------|----------|-------------|
-| `name` | string | Yes | Credential name |
-...
-```
+| 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 |
 
-### OpenAPI 3.0
+## Output Examples
 
-Standard OpenAPI specification for use with Swagger UI, Postman, etc.
+### OpenAPI 3.0
 
 ```json
 {
   "openapi": "3.0.0",
   "info": {
-    "title": "My API",
+    "title": "LokiCMS REST API",
     "version": "1.0.0"
   },
   "paths": {
-    "/mcp/vault_create": {
+    "/api/auth/login": {
       "post": {
-        "summary": "Create a new credential",
-        ...
+        "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" }
+    }
   }
 }
 ```
 
-### TypeScript
+### Markdown
 
-Generated TypeScript interfaces for type-safe frontend integration:
+```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
 
 ```typescript
 /**
- * Create a new credential
+ * Entry content object
  */
-export interface VaultCreateInput {
-  /** Credential name */
-  name: string;
-  /** Credential value */
-  value: string;
-  /** Project identifier */
-  project: string;
-  // ...
+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;
 }
 ```
 
@@ -181,7 +268,6 @@ const docGen = getDocGenerator();
 
 // Generate documentation
 const docs = await docGen.generate({
-  includeTools: true,
   includeContentTypes: true,
   includeExamples: true,
 });
@@ -194,6 +280,12 @@ const openApiSpec = formatAsOpenApi(docs, {
 // 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
@@ -215,6 +307,29 @@ interface ApiDocsConfig {
 }
 ```
 
+## Frontend Integration
+
+Use the generated OpenAPI spec or TypeScript types for frontend development:
+
+1. **Export OpenAPI spec:**
+```json
+{ "format": "openapi", "outputPath": "./docs/api.json" }
+```
+
+2. **Generate TypeScript client:**
+```bash
+npx openapi-typescript ./docs/api.json -o ./src/api-types.ts
+```
+
+3. **Use with fetch/axios:**
+```typescript
+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

package/dist/formatters/openapi-formatter.d.ts

@@ -1,6 +1,6 @@
 /**
  * OpenAPI Formatter
- * Outputs API documentation as OpenAPI 3.0 specification
+ * Outputs REST API documentation as OpenAPI 3.0 specification
  */
 import type { ApiDocumentation } from '../types.js';
 /**