ByteDocs NestJS Package

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

Features

• 🚀 Auto Route Detection - Automatically discovers and documents all your NestJS routes using AST parsing
• 🔍 Deep Object Detection - Automatically detects and displays nested object structures, DTOs, and entities
• 📄 OpenAPI YAML Export - Export complete OpenAPI 3.0 spec in YAML format with one click
• 🎨 Beautiful Modern UI - Clean, responsive interface with dark mode support
• 🤖 AI Integration - Built-in AI assistant to help users understand your API
• 📱 Mobile Responsive - Works perfectly on all device sizes
• 📊 OpenAPI Compatible - Generates standard OpenAPI 3.0 specifications with zero validation errors
• ⚡ Zero Configuration - Works out of the box with sensible defaults
• 🔧 Highly Customizable - Configure everything to match your needs

Installation

Install the package via npm:

npm install @bytedocs/nestjs

Quick Start

1. Import and Configure the Module

import { Module } from '@nestjs/common';
import { ByteDocsModule } from '@bytedocs/nestjs';

@Module({
  imports: [
    ByteDocsModule.forRoot({
      title: 'My API Documentation',
      version: '1.0.0',
      description: 'Comprehensive API for my application',
      baseURLs: [
        { name: 'Production', url: 'https://api.myapp.com' },
        { name: 'Development', url: 'http://localhost:3000' },
      ],
    }),
  ],
})
export class AppModule {}

2. Access Your Documentation

ByteDocs automatically detects all your routes! Just visit /docs to see your documentation.

3. Enhance with Decorators (Optional)

Use ByteDocs decorators to enhance your documentation:

import { Controller, Get, Post, Body, Param } from '@nestjs/common';
import {
  ApiDoc,
  ApiParameter,
  ApiRequestBody,
  ApiResponse
} from '@bytedocs/nestjs';

@Controller('users')
export class UsersController {
  @Get()
  @ApiDoc('Get all users', 'Retrieve a paginated list of users')
  @ApiParameter('page', {
    in: 'query',
    type: 'number',
    required: false,
    description: 'Page number for pagination'
  })
  @ApiParameter('limit', {
    in: 'query',
    type: 'number',
    required: false,
    description: 'Number of users per page'
  })
  @ApiResponse(200, {
    description: 'List of users',
    example: { data: [], meta: { total: 0 } }
  })
  async findAll(@Query() query: any) {
    // Your implementation
  }

  @Post()
  @ApiDoc('Create a new user')
  @ApiRequestBody({
    description: 'User data',
    example: { name: 'John Doe', email: '[email protected]' }
  })
  @ApiResponse(201, {
    description: 'User created successfully',
    example: { id: 1, name: 'John Doe', email: '[email protected]' }
  })
  async create(@Body() createUserDto: any) {
    // Your implementation
  }

  @Get(':id')
  @ApiDoc('Get user by ID')
  @ApiParameter('id', {
    in: 'path',
    type: 'number',
    required: true,
    description: 'User ID'
  })
  async findOne(@Param('id') id: string) {
    // Your implementation
  }
}

Configuration

Basic Configuration

ByteDocsModule.forRoot({
  title: 'My API Documentation',
  version: '1.0.0',
  description: 'Comprehensive API for my application',

  baseURLs: [
    { name: 'Production', url: 'https://api.myapp.com' },
    { name: 'Staging', url: 'https://staging-api.myapp.com' },
    { name: 'Local', url: 'http://localhost:3000' },
  ],

  docsPath: '/docs',
  autoDetect: true,
  excludePaths: ['health', 'metrics'],
})

AI Integration

Enable AI assistance for your API documentation:

ByteDocsModule.forRoot({
  title: 'My API Documentation',

  aiConfig: {
    enabled: true,
    provider: 'openai', // openai, gemini, claude, openrouter
    apiKey: process.env.BYTEDOCS_AI_API_KEY,

    features: {
      chatEnabled: true,
      model: 'gpt-4o-mini',
      maxTokens: 1000,
      temperature: 0.7,
    },
  },
})

Add to your .env file:

BYTEDOCS_AI_API_KEY=sk-your-api-key-here

UI Customization

ByteDocsModule.forRoot({
  title: 'My API Documentation',

  uiConfig: {
    theme: 'auto', // light, dark, auto
    showTryIt: true,
    showSchemas: true,
    customCss: '/assets/custom-docs.css',
    favicon: '/assets/api-favicon.ico',
  },
})

API Endpoints

Once installed, ByteDocs provides these endpoints:

• GET /docs - Main documentation interface
• GET /docs/api-data.json - Raw documentation data
• GET /docs/openapi.json - OpenAPI 3.0 specification
• POST /docs/chat - AI chat endpoint (if enabled)

Environment Variables

# AI Configuration (optional)
BYTEDOCS_AI_API_KEY=sk-your-key-here

Available Decorators

Route Documentation

• @ApiDoc(summary, description?) - Document endpoint with summary and description
• @ApiTags(...tags) - Add tags to group endpoints
• @ApiDeprecated(reason?) - Mark endpoint as deprecated
• @ApiExclude() - Exclude endpoint from documentation

Parameters

• @ApiParameter(name, options) - Document a single parameter
• @ApiParameters(parameters[]) - Document multiple parameters

Request/Response

• @ApiRequestBody(options) - Document request body
• @ApiResponse(statusCode, options) - Document a response
• @ApiResponses(responses[]) - Document multiple responses

Supported AI Providers

OpenAI

aiConfig: {
  provider: 'openai',
  apiKey: process.env.OPENAI_API_KEY,
  features: {
    model: 'gpt-4o-mini', // or gpt-4, gpt-3.5-turbo
  },
}

Google Gemini (Coming Soon)

aiConfig: {
  provider: 'gemini',
  apiKey: process.env.GEMINI_API_KEY,
  features: {
    model: 'gemini-1.5-flash',
  },
}

Claude (Coming Soon)

aiConfig: {
  provider: 'claude',
  apiKey: process.env.ANTHROPIC_API_KEY,
  features: {
    model: 'claude-3-sonnet-20240229',
  },
}

Requirements

• Node.js 16+
• NestJS 10+

Migration from Swagger

ByteDocs can work alongside existing Swagger documentation. Simply install and configure ByteDocs, and it will automatically detect your routes without interfering with existing Swagger decorators.

Contributing

1. Fork the repository
2. Create your feature branch (git checkout -b feature/amazing-feature)
3. Commit your changes (git commit -m 'Add some amazing feature')
4. Push to the branch (git push origin feature/amazing-feature)
5. Open a Pull Request

License

The MIT License (MIT). Please see License File for more information.

Support

• 📖 Documentation
• 🐛 Report Issues
• 💬 Discussions