Configuration

Configure Bytedocs for your needs

Customize Bytedocs to match your requirements with comprehensive configuration options.

Configuration Methods

Bytedocs can be configured through:

  1. Code Configuration - Direct object/struct configuration
  2. Environment Variables - .env file or system environment
  3. Config Files - Framework-specific config files

Basic Configuration

Go

config := &core.Config{
    Title:       "My API",
    Version:     "1.0.0",
    Description: "API documentation",
    DocsPath:    "/docs",
    AutoDetect:  true,
}

Laravel

// config/bytedocs.php
return [
    'title' => env('BYTEDOCS_TITLE', 'My API'),
    'version' => env('BYTEDOCS_VERSION', '1.0.0'),
    'description' => env('BYTEDOCS_DESCRIPTION', ''),
    'docs_path' => env('BYTEDOCS_DOCS_PATH', '/docs'),
    'auto_detect' => env('BYTEDOCS_AUTO_DETECT', true),
];

Node.js

setupByteDocs(app, {
  title: 'My API',
  version: '1.0.0',
  description: 'API documentation',
  docsPath: '/docs',
  autoDetect: true,
});

Python

setup_bytedocs(app, {
    "title": "My API",
    "version": "1.0.0",
    "description": "API documentation",
    "docs_path": "/docs",
    "auto_detect": True,
})

Rust

let config = Config {
    title: "My API".to_string(),
    version: "1.0.0".to_string(),
    description: "API documentation".to_string(),
    docs_path: "/docs".to_string(),
    ..Default::default()
};

Complete Configuration Reference

Core Settings

OptionTypeDefaultDescription
titlestring"API Documentation"API title
versionstring"1.0.0"API version
descriptionstring""API description
docs_pathstring"/docs"Documentation URL path
auto_detectbooleantrueEnable auto-detection
enabledbooleantrueEnable/disable docs

Multiple Environments

Configure multiple base URLs for different environments:

config := &core.Config{
    Title:   "My API",
    Version: "1.0.0",
    BaseURLs: []core.BaseURLOption{
        {
            Name: "Production",
            URL:  "https://api.example.com",
        },
        {
            Name: "Staging",
            URL:  "https://staging.example.com",
        },
        {
            Name: "Development",
            URL:  "http://localhost:8080",
        },
    },
}

Authentication

See Authentication Guide for detailed setup.

Quick example:

config.AuthConfig = &core.AuthConfig{
    Enabled:  true,
    Type:     "session",  // or: basic, api_key, bearer
    Username: "admin",
    Password: "secret",
}

AI Configuration

See AI Assistant for detailed setup.

Quick example:

config.AIConfig = &ai.AIConfig{
    Enabled:  true,
    Provider: "openai",  // or: gemini, claude, openrouter
    APIKey:   os.Getenv("OPENAI_API_KEY"),
    Features: ai.AIFeatures{
        Model:       "gpt-4o-mini",
        MaxTokens:   1000,
        Temperature: 0.7,
    },
}

UI Customization

config.UIConfig = &core.UIConfig{
    Theme:       "auto",  // light, dark, auto
    ShowTryIt:   true,
    ShowSchemas: true,
    CustomCSS:   "/css/custom.css",
    Favicon:     "/favicon.ico",
}

Route Filtering

Exclude specific routes from documentation:

config.ExcludePaths = []string{
    "/_internal",
    "/health",
    "/metrics",
    "/debug",
    "_ignition",
    "telescope",
}

Environment Variables

All configuration can be set via environment variables:

Core Settings

BYTEDOCS_TITLE="My API"
BYTEDOCS_VERSION="1.0.0"
BYTEDOCS_DESCRIPTION="My awesome API"
BYTEDOCS_DOCS_PATH="/docs"
BYTEDOCS_AUTO_DETECT=true
BYTEDOCS_ENABLED=true

Multiple Environments

BYTEDOCS_PRODUCTION_URL="https://api.example.com"
BYTEDOCS_STAGING_URL="https://staging.example.com"
BYTEDOCS_DEVELOPMENT_URL="http://localhost:8080"
BYTEDOCS_LOCAL_URL="http://localhost:8080"

Authentication

BYTEDOCS_AUTH_ENABLED=true
BYTEDOCS_AUTH_TYPE=session
BYTEDOCS_AUTH_USERNAME=admin
BYTEDOCS_AUTH_PASSWORD=secret
BYTEDOCS_AUTH_SESSION_EXPIRE=1440
BYTEDOCS_AUTH_IP_BAN_ENABLED=true
BYTEDOCS_AUTH_IP_BAN_MAX_ATTEMPTS=5
BYTEDOCS_AUTH_IP_BAN_DURATION=60

AI Configuration

BYTEDOCS_AI_ENABLED=true
BYTEDOCS_AI_PROVIDER=openai
BYTEDOCS_AI_API_KEY=sk-...
BYTEDOCS_AI_MODEL=gpt-4o-mini
BYTEDOCS_AI_MAX_TOKENS=1000
BYTEDOCS_AI_TEMPERATURE=0.7

UI Configuration

BYTEDOCS_UI_THEME=auto
BYTEDOCS_UI_SHOW_TRY_IT=true
BYTEDOCS_UI_SHOW_SCHEMAS=true
BYTEDOCS_UI_CUSTOM_CSS=/css/custom.css
BYTEDOCS_UI_FAVICON=/favicon.ico

Configuration by Environment

Development

if os.Getenv("ENVIRONMENT") == "development" {
    config = &core.Config{
        Title:      "My API (Dev)",
        Version:    "1.0.0-dev",
        AutoDetect: true,
        Debug:      true,
        AuthConfig: nil,  // No auth in dev
    }
}

Staging

if os.Getenv("ENVIRONMENT") == "staging" {
    config = &core.Config{
        Title:   "My API (Staging)",
        Version: "1.0.0-rc",
        AuthConfig: &core.AuthConfig{
            Enabled:  true,
            Type:     "basic",
            Username: "staging",
            Password: os.Getenv("STAGING_PASSWORD"),
        },
    }
}

Production

if os.Getenv("ENVIRONMENT") == "production" {
    config = &core.Config{
        Title:      "My API",
        Version:    "1.0.0",
        AutoDetect: false,  // Use pre-generated docs
        AuthConfig: &core.AuthConfig{
            Enabled:           true,
            Type:              "session",
            Password:          os.Getenv("DOCS_PASSWORD"),
            IPBanEnabled:      true,
            AdminWhitelistIPs: []string{"10.0.0.0/8"},
        },
    }
}

Configuration Validation

Required Fields

Minimum required configuration:

config := &core.Config{
    Title:   "My API",    // Required
    Version: "1.0.0",     // Required
}

Validation Errors

if config.Title == "" {
    return errors.New("title is required")
}

if config.Version == "" {
    return errors.New("version is required")
}

if config.DocsPath == "" {
    config.DocsPath = "/docs"  // Use default
}

Advanced Configuration

Custom Schemas

Register custom schemas manually:

docs := core.NewAPIDocs(config)

docs.AddSchema("User", map[string]interface{}{
    "type": "object",
    "properties": map[string]interface{}{
        "id":    map[string]string{"type": "integer"},
        "name":  map[string]string{"type": "string"},
        "email": map[string]string{"type": "string"},
    },
    "required": []string{"name", "email"},
})

Custom Routes

Add routes manually:

docs.AddRoute("GET", "/custom", nil,
    core.WithSummary("Custom endpoint"),
    core.WithDescription("Manually added endpoint"),
    core.WithParameters([]core.Parameter{
        {
            Name:     "id",
            In:       "path",
            Required: true,
            Type:     "integer",
        },
    }),
    core.WithResponse(200, "Success", userSchema),
)

Middleware Configuration

config.Middlewares = []core.MiddlewareFunc{
    func(endpoint *core.Endpoint) *core.Endpoint {
        // Modify endpoint before generation
        endpoint.Tags = append(endpoint.Tags, "Modified")
        return endpoint
    },
}

Configuration Best Practices

1. Use Environment Variables

# .env file
BYTEDOCS_TITLE="My Production API"
BYTEDOCS_AUTH_PASSWORD="${SECURE_PASSWORD}"
BYTEDOCS_AI_API_KEY="${OPENAI_KEY}"

config := &core.Config{
    Title:    os.Getenv("BYTEDOCS_TITLE"),
    Password: os.Getenv("BYTEDOCS_AUTH_PASSWORD"),
}

2. Separate Configs by Environment

func loadConfig() *core.Config {
    env := os.Getenv("ENVIRONMENT")

    switch env {
    case "production":
        return productionConfig()
    case "staging":
        return stagingConfig()
    default:
        return developmentConfig()
    }
}

3. Validate Configuration

func validateConfig(config *core.Config) error {
    if config.Title == "" {
        return errors.New("title required")
    }

    if config.AuthConfig != nil && config.AuthConfig.Enabled {
        if config.AuthConfig.Password == "" {
            return errors.New("auth password required")
        }
    }

    return nil
}

4. Document Your Config

// Config holds all Bytedocs configuration
type Config struct {
    // Title of the API (shown in documentation)
    Title string

    // Version following semantic versioning (e.g., "1.0.0")
    Version string

    // Description provides additional context about the API
    Description string
}

Troubleshooting

Configuration Not Applied

  1. Check load order:
// ✅ Correct - Config before setup
config := loadConfig()
setupBytedocs(app, config)

// ❌ Wrong - Setup before config
setupBytedocs(app, config)
config.Title = "New Title"  // Too late!
  1. Verify environment variables:
# Check if variables are loaded
echo $BYTEDOCS_TITLE

# Or in code
log.Println("Title:", os.Getenv("BYTEDOCS_TITLE"))

Authentication Not Working

See Authentication Troubleshooting

AI Not Responding

See AI Troubleshooting

What's Next?

Edit this page
Core Concepts
Understanding how Bytedocs works under the hood
Features
Explore Bytedocs' powerful features