oc-test

Express.js middleware for rendering Bruno Playground - API documentation made easy with server-side rendering.

Features

• 🚀 Express.js Integration: Seamless middleware and route handlers
• 📚 Server-Side Rendering: Generate complete HTML with embedded playground
• 🎨 Customizable Themes: Light, dark, and auto themes
• 🔧 Easy Configuration: Simple object-based API collection format
• 🛡️ Security: XSS protection and safe HTML generation
• 📱 Responsive: Mobile-friendly API documentation
• ⚡ CDN Ready: Uses CDN-hosted assets for fast loading

Installation

npm install oc-test

Quick Start

const express = require('express');
const { playgroundHandler } = require('oc-test');

const app = express();

// Simple route handler
app.get('/api-docs', playgroundHandler({
  name: "My API",
  description: "My awesome API documentation",
  items: [{
    type: "http",
    method: "GET",
    url: "https://api.example.com/users",
    docs: "Get all users"
  }]
}));

app.listen(3000, () => {
  console.log('API docs available at http://localhost:3000/api-docs');
});

Usage Examples

1. Route Handler (Recommended)

const { playgroundHandler } = require('oc-test');

const githubAPI = {
  name: "GitHub API",
  description: "GitHub REST API endpoints",
  environments: [{
    name: "production",
    variables: [{
      name: "baseUrl",
      value: "https://api.github.com"
    }]
  }],
  items: [{
    type: "http",
    method: "GET", 
    url: "{{baseUrl}}/user",
    headers: [{
      name: "Authorization",
      value: "token YOUR_TOKEN"
    }],
    docs: "Get authenticated user"
  }]
};

app.get('/github', playgroundHandler(githubAPI, {
  title: "GitHub API Documentation",
  theme: "dark"
}));

2. Middleware Pattern

const { createPlaygroundMiddleware } = require('oc-test');

// Global middleware with default options
app.use(createPlaygroundMiddleware({
  theme: 'auto',
  logo: 'https://example.com/logo.png'
}));

app.get('/api-docs', (req, res) => {
  res.playground({
    name: "My API",
    items: [
      // your API endpoints
    ]
  }, {
    title: "Custom API Docs"
  });
});

3. Direct Rendering

const { renderPlayground } = require('oc-test');

app.get('/custom', (req, res) => {
  const html = renderPlayground({
    opencollection: {
      name: "Custom API",
      items: [{
        method: "POST",
        url: "/api/users",
        body: {
          name: "John Doe",
          email: "[email protected]"
        }
      }]
    },
    theme: "light",
    title: "Custom Documentation"
  });
  
  res.send(html);
});

API Reference

playgroundHandler(collection, options?)

Creates an Express route handler.

Parameters:

• collection (Object): Your API collection in OpenCollection format
• options (Object, optional): Playground configuration options

Returns: Express route handler function

createPlaygroundMiddleware(defaultOptions?)

Creates Express middleware that adds res.playground() method.

Parameters:

• defaultOptions (Object, optional): Default options for all playgrounds

Returns: Express middleware function

renderPlayground(options)

Renders playground HTML directly.

Parameters:

• options (Object): Complete playground configuration

Returns: HTML string

convertObjectToBruno(collection)

Converts OpenCollection format to Bruno format.

Parameters:

• collection (Object): OpenCollection format

Returns: Bruno collection object

Configuration Options

| Option | Type | Default | Description | |--------|------|---------|-------------| | opencollection | Object | Required | Your API collection | | title | String | "API Playground" | Page title | | theme | String | "auto" | Theme: "light", "dark", or "auto" | | logo | String | undefined | URL to your logo image | | hideSidebar | Boolean | false | Hide the sidebar navigation | | hideHeader | Boolean | false | Hide the header | | cdnUrl | String | CDN URL | Custom URL for playground assets |

OpenCollection Format

Define your API using this simple format:

{
  name: "API Name",
  description: "API description", 
  environments: [{
    name: "production",
    variables: [{
      name: "baseUrl",
      value: "https://api.example.com"
    }]
  }],
  items: [{
    type: "http",
    method: "GET",
    url: "{{baseUrl}}/endpoint",
    headers: [{
      name: "Authorization", 
      value: "Bearer {{token}}"
    }],
    params: [{
      name: "limit",
      value: "10",
      type: "query"
    }],
    body: {
      name: "example",
      value: "data"
    },
    docs: "Endpoint description"
  }],
  docs: "# API Documentation\n\nOverall API documentation here."
}

Complete Example

const express = require('express');
const { playgroundHandler, createPlaygroundMiddleware } = require('oc-test');

const app = express();

// Middleware approach
app.use(createPlaygroundMiddleware({
  theme: 'auto',
  logo: 'https://example.com/logo.png'
}));

// Multiple API documentations
const apis = {
  github: {
    name: "GitHub API",
    description: "GitHub REST API v3",
    environments: [{
      name: "production", 
      variables: [{ name: "baseUrl", value: "https://api.github.com" }]
    }],
    items: [{
      method: "GET",
      url: "{{baseUrl}}/user",
      headers: [{ name: "Authorization", value: "token YOUR_TOKEN" }],
      docs: "Get authenticated user"
    }]
  },
  
  stripe: {
    name: "Stripe API",
    description: "Stripe payment processing",
    items: [{
      method: "GET", 
      url: "https://api.stripe.com/v1/customers",
      headers: [{ name: "Authorization", value: "Bearer sk_test_..." }],
      docs: "List customers"
    }]
  }
};

// Route handlers
app.get('/', (req, res) => {
  res.send(`
    <h1>API Documentation</h1>
    <ul>
      <li><a href="/github">GitHub API</a></li>
      <li><a href="/stripe">Stripe API</a></li>
      <li><a href="/custom">Custom API</a></li>
    </ul>
  `);
});

app.get('/github', playgroundHandler(apis.github, { theme: 'dark' }));
app.get('/stripe', playgroundHandler(apis.stripe, { theme: 'light' }));

app.get('/custom', (req, res) => {
  res.playground({
    name: "Custom API",
    items: [{ method: "GET", url: "/api/test" }]
  });
});

const PORT = process.env.PORT || 3000;
app.listen(PORT, () => {
  console.log(`🚀 Server running on http://localhost:${PORT}`);
  console.log(`📖 API docs:`);
  console.log(`   • GitHub: http://localhost:${PORT}/github`);
  console.log(`   • Stripe: http://localhost:${PORT}/stripe`);
  console.log(`   • Custom: http://localhost:${PORT}/custom`);
});

TypeScript Support

Full TypeScript definitions are included:

import { playgroundHandler, OpenCollection } from 'oc-test';

const collection: OpenCollection = {
  name: "My API",
  items: [{
    type: "http",
    method: "GET",
    url: "https://api.example.com"
  }]
};

app.get('/docs', playgroundHandler(collection));

License

MIT

Contributing

Issues and pull requests welcome! Visit the GitHub repository for more information.