Skip to main content

Doc Engine Developer Guide

Doc Engine Developer Guide

Overview

Package: @bluefly/doc-engine Version: 1.0.0 License: MIT

Production-ready API documentation engine for LLM Platform services with OpenAPI-first architecture and Apidog integration.

Key Features

  • Interactive API Explorers: Swagger UI, ReDoc
  • Multi-Format Export: JSON, YAML, Postman collections
  • Apidog Integration: Native sync for team collaboration
  • Auto-Generated Docs: From OpenAPI 3.1 specifications
  • Clean Architecture: Domain, Application, Infrastructure, Presentation layers
  • Type-Safe: TypeScript + Zod validation throughout

Installation

npm install

Quick Start

Development

npm run dev

Server starts on http://localhost:4100

Production

npm run build
npm start

API Endpoints

Base URL: http://localhost:4100

Documentation

  • GET / - Service catalog
  • GET /explorer - Multi-service Swagger UI
  • GET /api/{service}/swagger - Service-specific Swagger UI
  • GET /api/{service}/redoc - Service-specific ReDoc
  • GET /api/{service}/openapi.json - OpenAPI spec (JSON)
  • GET /api/{service}/postman.json - Postman collection

Apidog Integration

  • GET /api/v1/apidog/connection - Test connection
  • GET /api/v1/apidog/projects - List projects
  • POST /api/v1/apidog/sync - Sync all services
  • POST /api/v1/apidog/sync/{service} - Sync single service

Apidog Integration

Setup

  1. Get Apidog API token from apidog.com
  2. Save token: 
    echo "your-token" > ~/.tokens/apidog.token
chmod 600 ~/.tokens/apidog.token

Usage

# Test connection
curl http://localhost:4100/api/v1/apidog/connection

# Sync all services
curl -X POST http://localhost:4100/api/v1/apidog/sync \
  -H "Content-Type: application/json" \
  -d '{"projectPrefix": "LLM", "groupByProject": true}'

# Pull latest spec
npm run apidog:pull -- --service agent-chat --output ../agent-chat/specs/openapi/agent-chat-api.yaml

Testing

npm test
npm run test:unit
npm run test:integration
npm run test:e2e

Tech Stack

  • Runtime: Node.js 20+
  • Language: TypeScript
  • Framework: Express
  • Validation: Zod
  • API Docs: Swagger UI, ReDoc
  • Testing: Vitest, Playwright

Documentation