{"_id":"@bytedocs/express","_rev":"2-e25a3f403b1c36449d72dbc042694145","name":"@bytedocs/express","dist-tags":{"latest":"1.0.1"},"versions":{"1.0.0":{"name":"@bytedocs/express","version":"1.0.0","keywords":["express","documentation","api","swagger","openapi","bytedocs","auto-documentation","api-doc","rest-api","nodejs","typescript","openai","ai-assistant"],"author":{"name":"ByteDocs Contributors"},"license":"MIT","_id":"@bytedocs/express@1.0.0","maintainers":[{"name":"aibnuhibban","email":"abd.ibnuhibban@gmail.com"}],"homepage":"https://github.com/idnexacloud/bytedocs-express#readme","bugs":{"url":"https://github.com/idnexacloud/bytedocs-express/issues"},"dist":{"shasum":"9086d44e87278534b9434bf64aee489d3ae5daab","tarball":"https://registry.npmjs.org/@bytedocs/express/-/express-1.0.0.tgz","fileCount":55,"integrity":"sha512-NnfpfUK2EAY5bl/GFUMuTQMn8Ez5OiTmtwIzC4gkzEimFRFn/GYNyr8pATPv6DUP4VStn04G/NVher9opdmXtw==","signatures":[{"sig":"MEUCIQCqRTV4SQJvC6VXk1tb+0szpAQh8l6hS0GU5xO9H8LnawIgVd8Y/OQf9VcTZdr+4J3k78N8wTmEEn9uoA78d8ywqfs=","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":544668},"main":"dist/index.js","types":"dist/index.d.ts","engines":{"node":">=16.0.0"},"gitHead":"907251e9609e92934f19dd0fecaf3dad88bea413","scripts":{"dev":"tsc --watch","test":"jest","build":"tsc && npm run copy-templates","example":"ts-node examples/basic/index.ts","copy-templates":"cp -r src/ui/templates dist/ui/","prepublishOnly":"npm run build"},"_npmUser":{"name":"aibnuhibban","email":"abd.ibnuhibban@gmail.com"},"repository":{"url":"git+https://github.com/idnexacloud/bytedocs-express.git","type":"git"},"_npmVersion":"10.7.0","description":"Alternative to Swagger with better design, auto-detection, and AI integration","directories":{},"_nodeVersion":"20.15.1","dependencies":{"dotenv":"^16.4.5","js-yaml":"^4.1.0","@babel/types":"^7.23.6","@babel/parser":"^7.23.6","cookie-parser":"^1.4.6","@babel/traverse":"^7.23.6"},"_hasShrinkwrap":false,"devDependencies":{"express":"^4.18.2","ts-node":"^10.9.2","typescript":"^5.3.3","@types/node":"^20.10.0","@types/express":"^4.17.21","@types/js-yaml":"^4.0.9","@types/cookie-parser":"^1.4.7"},"peerDependencies":{"express":"^4.18.0 || ^5.0.0"},"_npmOperationalInternal":{"tmp":"tmp/express_1.0.0_1762152478410_0.6112556282347341","host":"s3://npm-registry-packages-npm-production"}},"1.0.1":{"name":"@bytedocs/express","version":"1.0.1","description":"Alternative to Swagger with better design, auto-detection, and AI integration","main":"dist/index.js","types":"dist/index.d.ts","scripts":{"build":"tsc && npm run copy-templates","copy-templates":"cp -r src/ui/templates dist/ui/","dev":"tsc --watch","test":"jest","prepublishOnly":"npm run build","example":"ts-node examples/basic/index.ts"},"keywords":["express","documentation","api","swagger","openapi","bytedocs","auto-documentation","api-doc","rest-api","nodejs","typescript","openai","ai-assistant"],"author":{"name":"ByteDocs Contributors"},"license":"MIT","repository":{"type":"git","url":"git+https://github.com/idnexacloud/bytedocs-express.git"},"homepage":"https://github.com/idnexacloud/bytedocs-express#readme","bugs":{"url":"https://github.com/idnexacloud/bytedocs-express/issues"},"peerDependencies":{"express":"^4.18.0 || ^5.0.0"},"dependencies":{"@babel/parser":"^7.23.6","@babel/traverse":"^7.23.6","@babel/types":"^7.23.6","cookie-parser":"^1.4.6","dotenv":"^16.4.5","js-yaml":"^4.1.0"},"devDependencies":{"@types/cookie-parser":"^1.4.7","@types/express":"^4.17.21","@types/js-yaml":"^4.0.9","@types/node":"^20.10.0","express":"^4.18.2","ts-node":"^10.9.2","typescript":"^5.3.3"},"engines":{"node":">=16.0.0"},"_id":"@bytedocs/express@1.0.1","gitHead":"c5ebb79d37618aa2a7bc0fa94bfa953198efd169","_nodeVersion":"20.15.1","_npmVersion":"10.7.0","dist":{"integrity":"sha512-76xdIUDv9FmaXIPwHalrW0KS9RiZFBvhc96TT19qHh0icOcOKAOzv4vJC1ftkCKLe2f/HSdEPHhYCJ4TMRFqmw==","shasum":"46a5e8ae54dbc57248c211fb9ec6c7bb44bac181","tarball":"https://registry.npmjs.org/@bytedocs/express/-/express-1.0.1.tgz","fileCount":55,"unpackedSize":544672,"signatures":[{"keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U","sig":"MEUCIGg8J2I6u+AaJwbS+gbw02PYbe0DIfxlj/zO3X3KG8czAiEA/8q275oSrEwys/roXSelL8ZSQdxw98vCG6n7wjaSM4A="}]},"_npmUser":{"name":"aibnuhibban","email":"abd.ibnuhibban@gmail.com"},"directories":{},"maintainers":[{"name":"aibnuhibban","email":"abd.ibnuhibban@gmail.com"}],"_npmOperationalInternal":{"host":"s3://npm-registry-packages-npm-production","tmp":"tmp/express_1.0.1_1762279507017_0.8922831497520012"},"_hasShrinkwrap":false}},"time":{"created":"2025-11-03T06:47:58.297Z","modified":"2025-11-04T18:05:07.452Z","1.0.0":"2025-11-03T06:47:58.627Z","1.0.1":"2025-11-04T18:05:07.223Z"},"bugs":{"url":"https://github.com/idnexacloud/bytedocs-express/issues"},"author":{"name":"ByteDocs Contributors"},"license":"MIT","homepage":"https://github.com/idnexacloud/bytedocs-express#readme","keywords":["express","documentation","api","swagger","openapi","bytedocs","auto-documentation","api-doc","rest-api","nodejs","typescript","openai","ai-assistant"],"repository":{"type":"git","url":"git+https://github.com/idnexacloud/bytedocs-express.git"},"description":"Alternative to Swagger with better design, auto-detection, and AI integration","maintainers":[{"name":"aibnuhibban","email":"abd.ibnuhibban@gmail.com"}],"readme":"# ByteDocs for Express\n\n[![npm version](https://img.shields.io/badge/npm-%3E%3D18-blue.svg)](https://nodejs.org/)\n[![License](https://img.shields.io/badge/license-MIT-green.svg)](LICENSE)\n[![Documentation](https://img.shields.io/badge/docs-bytedocs-blue.svg)](https://github.com/aibnuhibban/bytedocs)\n\n**ByteDocs** is a modern alternative to Swagger with better design, auto-detection, and AI integration for Express.js applications. It automatically generates beautiful API documentation from your routes with zero configuration required.\n\n## Features\n\n- 🚀 **Auto Route Detection** - Automatically discovers routes, parameters, and data structures from your Express app\n- 🎨 **Beautiful Modern UI** - Clean, responsive interface with dark mode support\n- 🤖 **AI Integration** - Built-in AI assistant (OpenAI, Gemini, Claude, OpenRouter) to help users understand your API\n- 📱 **Mobile Responsive** - Works perfectly on all device sizes\n- 🔍 **Interactive Testing** - Try out endpoints directly from the documentation\n- 📊 **OpenAPI Compatible** - Exports standard OpenAPI 3.0.3 specification in JSON and YAML formats\n- 🔐 **Built-in Authentication** - Support for Basic Auth, API Key, Bearer Token, and Session authentication\n- ⚡ **Zero Configuration** - Works out of the box with sensible defaults\n- 🔧 **Multi-Framework Support** - Express, and more coming soon (Fastify, Koa, NestJS)\n- 🌍 **Environment Config** - Full `.env` file support with validation\n- 📝 **JSDoc Support** - Extracts documentation from JSDoc comments\n\n## Quick Start\n\n### 1. Install ByteDocs\n\n```bash\nnpm install @bytedocs/express\n```\n\n### 2. Add One Line to Your Code\n\n```javascript\nimport express from 'express';\nimport { setupByteDocs } from '@bytedocs/express';\n\nconst app = express();\napp.use(express.json());\n\n// Your API routes\napp.get('/api/users', (req, res) => {\n  res.json({ users: [] });\n});\n\napp.post('/api/users', (req, res) => {\n  res.status(201).json({ id: 1, ...req.body });\n});\n\n// Setup ByteDocs - that's it!\nsetupByteDocs(app, {\n  title: 'My API',\n  version: '1.0.0',\n  description: 'Auto-generated API documentation',\n  docsPath: '/docs',\n  autoDetect: true,\n});\n\napp.listen(3000, () => {\n  console.log('Server running on http://localhost:3000');\n  console.log('Docs available at http://localhost:3000/docs');\n});\n```\n\n### 3. Visit Your Documentation\n\nOpen http://localhost:3000/docs and enjoy your auto-generated API documentation!\n\n## API Endpoints\n\nOnce installed, ByteDocs provides these endpoints:\n\n- `GET /docs` - Main documentation interface with beautiful UI\n- `GET /docs/api-data.json` - Raw documentation data\n- `GET /docs/openapi.json` - OpenAPI 3.0.3 specification (JSON format)\n- `GET /docs/openapi.yaml` - OpenAPI 3.0.3 specification (YAML format)\n- `POST /docs/chat` - AI chat endpoint (if AI is enabled)\n- `GET /docs/login` - Login page (if session auth enabled)\n- `POST /docs/login` - Login handler (if session auth enabled)\n- `POST /docs/logout` - Logout handler (if session auth enabled)\n\n## Configuration\n\n### Basic Configuration\n\n```javascript\nsetupByteDocs(app, {\n  title: 'My API Documentation',\n  version: '1.0.0',\n  description: 'Comprehensive API for my application',\n  docsPath: '/docs',\n  autoDetect: true,\n\n  baseURLs: [\n    { name: 'Production', url: 'https://api.myapp.com' },\n    { name: 'Staging', url: 'https://staging-api.myapp.com' },\n    { name: 'Local', url: 'http://localhost:3000' },\n  ],\n});\n```\n\n### AI Integration\n\nEnable AI assistance for your API documentation:\n\n```javascript\nsetupByteDocs(app, {\n  title: 'My API',\n  version: '1.0.0',\n  aiConfig: {\n    enabled: true,\n    provider: 'openai', // openai, gemini, claude, openrouter\n    apiKey: process.env.OPENAI_API_KEY,\n    features: {\n      chatEnabled: true,\n      docGenerationEnabled: false,\n      model: 'gpt-4o-mini',\n      maxTokens: 1000,\n      temperature: 0.7,\n    },\n  },\n});\n```\n\n**Supported AI Providers:**\n\n### OpenAI\n```javascript\naiConfig: {\n  enabled: true,\n  provider: 'openai',\n  apiKey: process.env.OPENAI_API_KEY,\n  features: {\n    model: 'gpt-4o-mini', // or gpt-4, gpt-3.5-turbo\n  },\n}\n```\n\n### Google Gemini\n```javascript\naiConfig: {\n  enabled: true,\n  provider: 'gemini',\n  apiKey: process.env.GEMINI_API_KEY,\n  features: {\n    model: 'gemini-1.5-flash', // or gemini-1.5-pro\n  },\n}\n```\n\n### Anthropic Claude\n```javascript\naiConfig: {\n  enabled: true,\n  provider: 'claude',\n  apiKey: process.env.ANTHROPIC_API_KEY,\n  features: {\n    model: 'claude-3-sonnet-20240229',\n  },\n}\n```\n\n### OpenRouter\n```javascript\naiConfig: {\n  enabled: true,\n  provider: 'openrouter',\n  apiKey: process.env.OPENROUTER_API_KEY,\n  features: {\n    model: 'openai/gpt-4o-mini', // Any OpenRouter model\n  },\n}\n```\n\n### Authentication\n\nProtect your documentation with built-in authentication:\n\n```javascript\nsetupByteDocs(app, {\n  title: 'My API',\n  version: '1.0.0',\n  authConfig: {\n    enabled: true,\n    type: 'session', // basic, api_key, bearer, session\n    username: 'admin',\n    password: 'secret',\n    realm: 'API Documentation',\n\n    // Session-specific settings\n    sessionExpire: 1440, // minutes\n    ipBanEnabled: true,\n    ipBanMaxAttempts: 5,\n    ipBanDuration: 60, // minutes\n    adminWhitelistIPs: ['127.0.0.1', '::1'],\n  },\n});\n```\n\n**Authentication Types:**\n- `basic` - HTTP Basic Authentication\n- `api_key` - API Key authentication via custom header\n- `bearer` - Bearer token authentication\n- `session` - Session-based authentication with login page\n\n### Environment Configuration\n\nCreate a `.env` file for easy configuration:\n\n```bash\n# Basic Settings\nBYTEDOCS_TITLE=\"My API Documentation\"\nBYTEDOCS_VERSION=\"1.0.0\"\nBYTEDOCS_DESCRIPTION=\"Comprehensive API for my application\"\nBYTEDOCS_DOCS_PATH=\"/docs\"\nBYTEDOCS_AUTO_DETECT=true\n\n# Multiple Environment URLs\nBYTEDOCS_PRODUCTION_URL=\"https://api.myapp.com\"\nBYTEDOCS_STAGING_URL=\"https://staging-api.myapp.com\"\nBYTEDOCS_LOCAL_URL=\"http://localhost:3000\"\n\n# Authentication\nBYTEDOCS_AUTH_ENABLED=true\nBYTEDOCS_AUTH_TYPE=session\nBYTEDOCS_AUTH_USERNAME=admin\nBYTEDOCS_AUTH_PASSWORD=your-secret-password\nBYTEDOCS_AUTH_SESSION_EXPIRE=1440\nBYTEDOCS_AUTH_IP_BAN_ENABLED=true\nBYTEDOCS_AUTH_IP_BAN_MAX_ATTEMPTS=5\nBYTEDOCS_AUTH_IP_BAN_DURATION=60\nBYTEDOCS_AUTH_ADMIN_WHITELIST_IPS=127.0.0.1,::1\n\n# AI Configuration\nBYTEDOCS_AI_ENABLED=true\nBYTEDOCS_AI_PROVIDER=openai\nBYTEDOCS_AI_API_KEY=sk-your-openai-key\nBYTEDOCS_AI_MODEL=gpt-4o-mini\nBYTEDOCS_AI_MAX_TOKENS=1000\nBYTEDOCS_AI_TEMPERATURE=0.7\n\n# UI Customization\nBYTEDOCS_UI_THEME=auto\nBYTEDOCS_UI_SHOW_TRY_IT=true\nBYTEDOCS_UI_SHOW_SCHEMAS=true\n```\n\nThen load it in your code:\n```javascript\nimport { loadConfigFromEnv, validateConfig } from '@bytedocs/express';\n\nconst config = loadConfigFromEnv();\n\n// Validate configuration\nconst errors = validateConfig(config);\nif (errors.length > 0) {\n  console.error('Configuration errors:', errors);\n  process.exit(1);\n}\n\nsetupByteDocs(app, config);\n```\n\n## Framework Support\n\nByteDocs currently supports Express with more frameworks coming soon:\n\n### Express\n```javascript\nimport express from 'express';\nimport { setupByteDocs } from '@bytedocs/express';\n\nconst app = express();\nsetupByteDocs(app, config);\n```\n\n### Coming Soon\n- Fastify\n- Koa\n- NestJS\n- Hono\n\n## JSDoc Annotations\n\nEnhance your documentation with JSDoc comments:\n\n```javascript\n/**\n * Get user by ID\n * @summary Retrieve a specific user\n * @tag Users\n * @param id path string true \"User ID to retrieve\"\n * @response 200 {object} User \"User object\"\n * @response 404 {object} Error \"User not found\"\n */\napp.get('/api/users/:id', (req, res) => {\n  const user = getUserById(req.params.id);\n  if (user) {\n    res.json(user);\n  } else {\n    res.status(404).json({ error: 'User not found' });\n  }\n});\n\n/**\n * Create a new user\n * @summary Create user\n * @tag Users\n * @description Creates a new user with the provided information\n * @body {object} UserInput \"User data\"\n * @response 201 {object} User \"Created user\"\n */\napp.post('/api/users', (req, res) => {\n  const user = createUser(req.body);\n  res.status(201).json(user);\n});\n```\n\n## Advanced Usage\n\n### Manual Route Registration\n\n```javascript\nimport { ByteDocs } from '@bytedocs/express';\n\nconst docs = new ByteDocs({\n  title: 'My API',\n  version: '1.0.0',\n});\n\n// Manually add route information\ndocs.addRoute({\n  method: 'GET',\n  path: '/api/custom-endpoint',\n  summary: 'Custom endpoint',\n  description: 'This is a manually registered endpoint',\n  parameters: [\n    {\n      name: 'id',\n      in: 'path',\n      type: 'integer',\n      required: true,\n      description: 'Record ID',\n    },\n  ],\n});\n\n// Generate documentation\ndocs.generate();\n```\n\n### Export OpenAPI Specifications\n\n```javascript\n// Get OpenAPI JSON\nconst openAPIJSON = docs.getOpenAPIJSON();\n\n// Get OpenAPI YAML\nconst openAPIYAML = docs.getOpenAPIYAML();\n\n// Save to file\nimport fs from 'fs';\nfs.writeFileSync('openapi.yaml', openAPIYAML);\n```\n\n## Requirements\n\n- Node.js 18 or higher\n- Express 4.x or higher\n\n## Development\n\n### Prerequisites\n- Node.js 18 or higher\n- npm or yarn\n\n### Build from Source\n\n```bash\n# Clone the repository\ngit clone https://github.com/aibnuhibban/bytedocs-node.git\ncd bytedocs-node/express\n\n# Install dependencies\nnpm install\n\n# Build the package\nnpm run build\n\n# Run example\nnpm run example\n# Visit http://localhost:3000/docs\n```\n\n### Development Mode\n\n```bash\n# Start development server with hot reload\nnpm run dev\n```\n\n### Available Commands\n\n```bash\nnpm run build      # Build the package\nnpm run dev        # Development mode with hot reload\nnpm test           # Run tests\nnpm run lint       # Lint code\nnpm run example    # Run example server\n```\n\n## Project Structure\n\n```\n@bytedocs/express/\n  src/\n    core/              # Core functionality\n    parser/            # Route parser\n    ai/                # AI/LLM integration\n    auth/              # Authentication middleware\n    ui/                # Web UI components\n  examples/            # Example applications\n    basic/\n    with-auth/\n    with-ai/\n  dist/                # Built files\n  tests/               # Test files\n```\n\n## Examples\n\nCheck out the `examples/` directory for complete implementations:\n\n- **Basic**: `examples/basic/` - Simple setup without authentication\n- **With Auth**: `examples/with-auth/` - Session-based authentication example\n- **With AI**: `examples/with-ai/` - AI integration example\n- **Advanced**: `examples/advanced/` - Full-featured example with all options\n\nEach example demonstrates:\n- Basic setup and configuration\n- Route auto-detection\n- AI integration (optional)\n- Authentication setup\n- Custom documentation\n- JSDoc annotations\n\nTo run examples:\n\n```bash\n# Install dependencies\nnpm install\n\n# Run basic example\nnpm run example:basic\n\n# Run with authentication\nnpm run example:auth\n\n# Run with AI\nnpm run example:ai\n```\n\n## Contributing\n\nWe welcome contributions! Please see [CONTRIBUTING.md](CONTRIBUTING.md) for guidelines.\n\n### Development Setup\n\n1. Fork the repository\n2. Create a feature branch (`git checkout -b feature/amazing-feature`)\n3. Make your changes\n4. Add tests if applicable\n5. Run `npm test` to ensure everything works\n6. Commit your changes (`git commit -m 'Add some amazing feature'`)\n7. Push to the branch (`git push origin feature/amazing-feature`)\n8. Open a Pull Request\n\n## License\n\nThis project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.\n\n## Support\n\n- 📖 [Documentation](https://github.com/aibnuhibban/bytedocs)\n- 🐛 [Report Issues](https://github.com/aibnuhibban/bytedocs-node/issues)\n- 💬 [GitHub Discussions](https://github.com/aibnuhibban/bytedocs/discussions)\n\n## Credits\n\n- Inspired by [Scramble for Laravel](https://scramble.dedoc.co/)\n- Part of the ByteDocs project\n- UI based on modern React and Tailwind CSS\n\n---\n\n**Made with ❤️ for the Express community**\n","readmeFilename":"README.md"}