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: bash 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

• GitLab: https://app-4001.cloud.bluefly.io/llm/npm/doc-engine
• OpenAPI Specs: openapi/