FlexDoc - OpenAPI Documentation Generator

FlexDoc is a beautiful, highly customizable OpenAPI documentation generator that can be easily integrated into backend applications. It provides a modern, interactive interface for API documentation with advanced features and customization options.

Features

• 🎨 Beautiful UI: Modern, responsive design with smooth animations and micro-interactions
• 📱 Mobile-First: Fully responsive design that works on all devices
• 🎯 Interactive: Live API explorer with request/response examples
• 🔍 Advanced Search: Powerful search and filtering capabilities
• 🎨 Customizable: Extensive theming and styling options
• 🔒 Authentication: Secure your documentation with Basic or Bearer token authentication
• ⚡ Fast: Optimized performance with lazy loading and efficient rendering
• 🔧 Easy Integration: Simple setup for NestJS and other frameworks
• 📖 OpenAPI 3.0: Full support for OpenAPI 3.0 specifications

Quick Start

React Component (Standalone)

npm install @bluejeans/flexdoc

import { FlexDoc } from '@bluejeans/flexdoc';
import { openApiSpec } from './your-spec';

function App() {
  return (
    <FlexDoc
      spec={openApiSpec}
      theme='light'
      customStyles={{ fontFamily: 'Inter' }}
    />
  );
}

NestJS Integration

npm install @bluejeans/flexdoc-backend

// app.module.ts
import { Module } from '@nestjs/common';
import { FlexDocModule } from '@bluejeans/flexdoc-backend';

@Module({
  imports: [
    // Your other modules...
    FlexDocModule.forRoot({
      path: 'api-docs',
      options: {
        title: 'My API Documentation',
        hideHostname: true,
        pathInMiddlePanel: true,
        // Enable authentication (optional)
        auth: {
          type: 'basic', // or 'bearer'
          secretKey: process.env.FLEXDOC_SECRET_KEY || 'your-strong-secret-key',
        },
      },
    }),
  ],
})
export class AppModule {}

Express Integration

import express from 'express';
import { setupFlexDoc } from '@bluejeans/flexdoc-backend';

const app = express();

// Your other routes and middleware...

// Set up FlexDoc
setupFlexDoc(app, {
  path: 'api-docs',
  options: {
    title: 'My API Documentation',
    hideHostname: true,
    pathInMiddlePanel: true,
    // Enable authentication (optional)
    auth: {
      type: 'basic', // or 'bearer'
      secretKey: process.env.FLEXDOC_SECRET_KEY || 'your-strong-secret-key',
    },
  },
});

app.listen(3000, () => {
  console.log('Server running on http://localhost:3000');
});

Authentication

FlexDoc supports two authentication methods to secure your API documentation:

Basic Authentication

// In your configuration
options: {
  auth: {
    type: 'basic',
    secretKey: process.env.FLEXDOC_SECRET_KEY
  }
}

Generate credentials for users:

# Using the CLI tool
npx ts-node generate-auth.ts basic --username admin --secret your-strong-secret-key

Bearer Authentication (JWT)

// In your configuration
options: {
  auth: {
    type: 'bearer',
    secretKey: process.env.FLEXDOC_SECRET_KEY
  }
}

Generate JWT tokens:

# Using the CLI tool
npx ts-node generate-auth.ts bearer --expiry 30 --secret your-strong-secret-key

For more details, see the Authentication Guide.

Configuration Options

FlexDocOptions

interface FlexDocOptions {
  title?: string; // Page title
  description?: string; // Page description
  theme?: 'light' | 'dark' | ThemeOptions; // Color theme
  customCss?: string; // Custom CSS styles
  customJs?: string; // Custom JavaScript
  favicon?: string; // Custom favicon URL
  logo?: string; // Custom logo URL
  hideHostname?: boolean; // Hide hostname in API endpoints
  pathInMiddlePanel?: boolean; // Show path in middle panel

  // Authentication
  auth?: {
    type: 'basic' | 'bearer';
    secretKey: string;
  };

  // Advanced theming
  theme_?: {
    colors?: {
      primary?: string; // Primary brand color
      secondary?: string; // Secondary color
      accent?: string; // Accent color
      background?: string; // Background color
      surface?: string; // Surface color
      text?: string; // Text color
      textSecondary?: string; // Secondary text color
      border?: string; // Border color
    };
    typography?: {
      fontSize?: string; // Base font size
      fontFamily?: string; // Font family
      lineHeight?: string; // Line height
    };
    spacing?: {
      unit?: number; // Base spacing unit
    };
  };
}

For a complete list of configuration options, see the Configuration Guide.

Examples

Basic Usage

FlexDocModule.forRoot({
  path: 'api-docs',
  options: {
    title: 'Pet Store API',
    description: 'Beautiful API documentation',
    theme: 'light',
  },
});

Custom Theming

FlexDocModule.forRoot({
  path: 'api-docs',
  options: {
    title: 'My API',
    theme: {
      primaryColor: '#6366f1',
      secondaryColor: '#10b981',
      backgroundColor: '#ffffff',
      textColor: '#333333',
    },
    customCss: `
      .flexdoc-container {
        --border-radius: 12px;
      }
      .method-badge {
        border-radius: var(--border-radius);
      }
    `,
  },
});

Secured Documentation with Authentication

FlexDocModule.forRoot({
  path: 'api-docs',
  options: {
    title: 'Internal API Documentation',
    theme: 'dark',
    auth: {
      type: 'basic', // or 'bearer'
      secretKey: process.env.FLEXDOC_SECRET_KEY,
    },
  },
});

Multiple Documentation Sites

// Public API docs
FlexDocModule.forRoot({
  path: 'public-docs',
  options: { title: 'Public API' },
});

// Internal API docs (with authentication)
FlexDocModule.forRoot({
  path: 'internal-docs',
  options: {
    title: 'Internal API',
    theme: 'dark',
    auth: {
      type: 'basic',
      secretKey: process.env.FLEXDOC_SECRET_KEY,
    },
  },
});

Running the Example

1. Clone the repository
2. Install dependencies:

   npm install

3. Navigate to the NestJS example:

   cd packages/examples/nestjs
   npm run start:dev

4. Open your browser:
   • FlexDoc: http://localhost:3000/api-docs

Comparison with Other Tools

Feature	FlexDoc	Redoc	Swagger UI
Modern UI	✅	✅	❌
Mobile Responsive	✅	✅	⚠️
Interactive Examples	✅	❌	✅
Advanced Search	✅	⚠️	❌
Custom Theming	✅	⚠️	⚠️
Authentication	✅	❌	⚠️
Performance	✅	✅	⚠️
Easy Integration	✅	✅	✅

Browser Support

• Chrome 90+
• Firefox 88+
• Safari 14+
• Edge 90+

Contributing

We welcome contributions! Please see our Contributing Guide for details.

Testing

FlexDoc uses Jest for testing both the client and backend packages. Each package has its own test configuration and coverage reports.

Client Tests

cd packages/client
npm test

To generate coverage reports:

cd packages/client
npm run test:coverage

Backend Tests

cd packages/backend
npm test

To generate coverage reports:

cd packages/backend
npm run test:coverage

License

MIT License - see LICENSE file for details.

Support

• 📖 Documentation
• 🐛 Issue Tracker
• 📧 Email Support

Documentation

• Getting Started
• Configuration Options
• Theming Guide
• Authentication
• API Reference
• Examples