ByteDocs Fastify

ByteDocs is a modern alternative to Swagger with better design, auto-detection, and AI integration for Hono applications. It automatically generates beautiful API documentation from your routes with zero configuration required.

Features

• 🔍 Auto-Discovery: Automatically detects all your Fastify routes and schemas
• 📝 Smart Analysis: Analyzes handler functions using AST to extract response structures
• 🎨 Beautiful UI: Modern, responsive documentation interface
• 🔐 Multiple Auth Methods: Support for Basic, API Key, Bearer Token, and Session authentication
• 🤖 AI-Powered: Optional AI assistant integration (OpenAI, Claude, OpenRouter)
• 📊 OpenAPI 3.0: Export full OpenAPI specification in JSON or YAML
• 🎯 TypeScript: Full TypeScript support with type definitions
• ⚡ Zero Config: Works out of the box with sensible defaults
• 🔌 Fastify Plugin: Easy integration as a standard Fastify plugin

📦 Installation

npm install @bytedocs/fastify
# or
yarn add @bytedocs/fastify

🚀 Quick Start

import Fastify from 'fastify';
import byteDocsPlugin from '@bytedocs/fastify';

const fastify = Fastify();

// Register ByteDocs plugin
await fastify.register(byteDocsPlugin, {
  title: 'My API',
  version: '1.0.0',
  description: 'API Documentation',
  baseURL: 'http://localhost:3000',
});

// Define your routes
fastify.get('/api/users', async (request, reply) => {
  return reply.send({
    success: true,
    data: [
      { id: 1, name: 'John Doe' },
      { id: 2, name: 'Jane Smith' },
    ],
  });
});

await fastify.listen({ port: 3000 });
// Documentation available at http://localhost:3000/docs

⚙️ Configuration

Programmatic Configuration

await fastify.register(byteDocsPlugin, {
  // Core settings
  title: 'My API Documentation',
  version: '1.0.0',
  description: 'API for my application',
  docsPath: '/docs',
  autoDetect: true,

  // Multiple base URLs (environments)
  baseURLs: [
    { name: 'Production', url: 'https://api.example.com' },
    { name: 'Staging', url: 'https://staging-api.example.com' },
    { name: 'Development', url: 'http://localhost:3000' },
  ],

  // Authentication
  authConfig: {
    enabled: true,
    type: 'session', // 'basic' | 'api_key' | 'bearer' | 'session'
    password: 'your-secure-password',
  },

  // UI Configuration
  uiConfig: {
    theme: 'blue', // 'green' | 'blue' | 'purple' | 'red' | 'orange' | 'teal' | 'pink'
    darkMode: false,
  },

  // AI Configuration (optional)
  aiConfig: {
    enabled: true,
    provider: 'openai', // 'openai' | 'claude' | 'openrouter'
    apiKey: process.env.OPENAI_API_KEY,
    features: {
      chatEnabled: true,
      model: 'gpt-4o-mini',
    },
  },
});

Environment Variables

Create a .env file:

# Core Configuration
BYTEDOCS_TITLE=My API Documentation
BYTEDOCS_VERSION=1.0.0
BYTEDOCS_DESCRIPTION=API for my application
BYTEDOCS_DOCS_PATH=/docs
BYTEDOCS_AUTO_DETECT=true

# Base URLs (Multiple Environments)
BYTEDOCS_PRODUCTION_URL=https://api.example.com
BYTEDOCS_STAGING_URL=https://staging-api.example.com
BYTEDOCS_DEVELOPMENT_URL=http://localhost:3000

# Authentication
BYTEDOCS_AUTH_ENABLED=true
BYTEDOCS_AUTH_TYPE=session
BYTEDOCS_AUTH_PASSWORD=your-secure-password

# UI Configuration
BYTEDOCS_UI_THEME=blue
BYTEDOCS_UI_DARK_MODE=false

# AI Configuration (Optional)
BYTEDOCS_AI_ENABLED=true
BYTEDOCS_AI_PROVIDER=openai
BYTEDOCS_AI_API_KEY=your-openai-api-key
BYTEDOCS_AI_CHAT_ENABLED=true
BYTEDOCS_AI_MODEL=gpt-4o-mini

📚 Documentation Features

Schema-First Approach

ByteDocs works great with Fastify's native JSON Schema validation:

fastify.post('/api/users', {
  schema: {
    body: {
      type: 'object',
      required: ['name', 'email'],
      properties: {
        name: { type: 'string', minLength: 1 },
        email: { type: 'string', format: 'email' },
      },
    },
    response: {
      201: {
        type: 'object',
        properties: {
          success: { type: 'boolean' },
          data: {
            type: 'object',
            properties: {
              id: { type: 'number' },
              name: { type: 'string' },
              email: { type: 'string' },
            },
          },
        },
      },
    },
  },
  handler: async (request, reply) => {
    const { name, email } = request.body;
    const newUser = { id: Date.now(), name, email };
    return reply.code(201).send({ success: true, data: newUser });
  },
});

JSDoc Comments

Add rich documentation using JSDoc:

/**
 * Get user by ID
 * @summary Retrieve a specific user
 * @tag Users
 * @param {string} id - User ID
 */
fastify.get('/api/users/:id', async (request, reply) => {
  // Handler implementation
});

Response Examples

Attach examples to handlers:

import { attachExamples } from '@bytedocs/fastify';

const handler = async (request, reply) => {
  return reply.send({ success: true, data: { id: 1, name: 'John' } });
};

attachExamples(handler,
  { name: 'John Doe', email: '[email protected]' },  // Request example
  { success: true, id: 1 }  // Response example
);

fastify.post('/api/users', handler);

🔐 Authentication

ByteDocs supports multiple authentication methods:

1. Session Authentication (Recommended)

authConfig: {
  enabled: true,
  type: 'session',
  password: 'your-secure-password',
  sessionExpire: 1440, // Minutes (24 hours)
  ipBanEnabled: true,
  ipBanMaxAttempts: 5,
  ipBanDuration: 30, // Minutes
}

2. Basic Authentication

authConfig: {
  enabled: true,
  type: 'basic',
  username: 'admin',
  password: 'password',
}

3. API Key Authentication

authConfig: {
  enabled: true,
  type: 'api_key',
  apiKey: 'your-api-key',
  apiKeyHeader: 'X-API-Key',
}

4. Bearer Token Authentication

authConfig: {
  enabled: true,
  type: 'bearer',
  apiKey: 'your-bearer-token',
}

🤖 AI Assistant

Enable AI-powered documentation assistance:

aiConfig: {
  enabled: true,
  provider: 'openai', // or 'claude', 'openrouter'
  apiKey: process.env.OPENAI_API_KEY,
  features: {
    chatEnabled: true,
    model: 'gpt-4o-mini',
    maxTokens: 4096,
    temperature: 0.7,
  },
}

The AI assistant can answer questions about your API endpoints, provide code examples, and help with integration.

📤 Export Options

OpenAPI JSON

Access the full OpenAPI specification:

http://localhost:3000/docs/openapi.json

OpenAPI YAML

Download as YAML:

http://localhost:3000/docs/openapi.yaml

🎨 Theming

Choose from multiple color themes:

• green (default)
• blue
• purple
• red
• orange
• teal
• pink

uiConfig: {
  theme: 'blue',
  darkMode: true,
}

📝 Examples

Check out the examples/ directory for complete working examples:

• examples/basic/ - Basic setup with auto-detection
• More examples coming soon!

🤝 Contributing

Contributions are welcome! Please see CONTRIBUTING.md for details.

📄 License

MIT License - see LICENSE for details.

Made with ❤️ by the ByteDocs team