@chargebee/code-samples

@chargebee/code-samples

A self-contained, reusable React component for generating and displaying API code samples from OpenAPI specifications.

Features

• Self-Contained: Generates code samples on-the-fly from OpenAPI specs
• Multi-Language: Supports 12+ languages (cURL, Node.js, Python, PHP, Ruby, Java, .NET, Go, TypeScript)
• Syntax Highlighting: Powered by Shiki
• Feature-Rich: Carousel, copy button, animations, language switcher
• Module Federation: Consumable across multiple apps via Vite Module Federation
• Themeable: Configurable themes and styling

Installation

pnpm add @chargebee/code-samples

Usage

import { CodeSamples } from '@chargebee/code-samples';
import '@chargebee/code-samples/styles';

function MyPage() {
  return (
    <CodeSamples
      openapi="/path/to/openapi.json"
      resource="customer"
      operation="delete_a_customer"
      apiVersion="v2"
      pcVersion="v2"
      theme="chargebee"
      features={{
        carousel: true,
        copyButton: true,
        animations: true,
      }}
    />
  );
}

Props

Prop	Type	Required	Description
openapi	string | OpenAPISpec	✅	OpenAPI spec URL or object
resource	string	✅	Resource name (e.g., "customer")
operation	string	✅	Operation name (e.g., "delete_a_customer")
apiVersion	"v1" | "v2"	❌	API version (default: "v2")
pcVersion	"v1" | "v2"	❌	Product Catalog version (default: "v2")
siteName	string	❌	Site name placeholder (default: "your-site")
apiKey	string	❌	API key placeholder (default: "test_api_key")
theme	string | ThemeConfig	❌	Theme configuration (default: "default")
highlighter	HighlighterConfig	❌	Shiki highlighter config
features	FeaturesConfig	❌	Feature toggles
onLanguageChange	(lang: string) => void	❌	Language change callback
onCopy	(code: string) => void	❌	Copy callback

Module Federation

This package is configured for Vite Module Federation, allowing it to be consumed by multiple applications without bundling duplication.

Host Configuration (api-docs example)

// vite.config.ts
import federation from '@originjs/vite-plugin-federation';

export default defineConfig({
  plugins: [
    federation({
      name: 'apiDocs',
      remotes: {
        codeSamples: 'http://localhost:5001/assets/remoteEntry.js',
      },
      shared: {
        react: { singleton: true },
        'react-dom': { singleton: true },
      },
    }),
  ],
});

Development

# Install dependencies
pnpm install

# Start dev server (port 5001)
pnpm dev

# Build for production
pnpm build

Code Sample Reporting Tools

This package includes tools to analyze and report on code sample generation across all OpenAPI operations.

Generate Operations Report

Generate a comprehensive report of all operations, their code sample status, and generation success/failure:

# Generate report for v2-pcv2 (default)
pnpm report:operations

# Generate report for specific version
pnpm report:operations --version v2-pcv2
pnpm report:operations --version v2-pcv1
pnpm report:operations --version v1

# Generate only JSON or Markdown
pnpm report:operations --format json
pnpm report:operations --format markdown

# Test with specific language
pnpm report:operations --test-lang java

Output: Reports are saved to reports/operations-report-{version}.{json|md}

View Reports

Open the interactive HTML viewer to filter and explore reports:

# Open the report viewer in your browser
open reports/report-viewer.html

# Or manually navigate to:
# packages/code-samples/reports/report-viewer.html

The viewer allows you to:

• Select version (v1, v2-pcv1, v2-pcv2) from dropdown
• Filter by resource, HTTP method, or status
• Search operations by name, path, or operationId
• Export filtered results as CSV
• View detailed error messages for failed operations

Report Structure

Each report includes:

• Summary: Total operations, with samples, successful, failed, missing samples
• Operations: Detailed list with:
  • Resource and operation name
  • HTTP method and path
  • Operation ID
  • Sample file status
  • Code generation status (success/failed/no_samples)
  • Error messages and categories

See README-REPORT.md for detailed documentation.

Architecture

• generators/: Language-specific code generators (Go, Node.js, Python, etc.)
• metadata/: OpenAPI metadata extraction
• components/: React UI components
• styles/: CSS themes and animations

Pure Function API (Non-React)

For non-React environments (Node.js, LLMs, Deno, Bun), use the pure function API:

import { generateCodeSample, generateCodeSamples } from '@chargebee/code-samples';

// Generate code for a specific language
const result = await generateCodeSample({
  language: 'node-v3',
  resource: 'customer',
  operation: 'create_a_customer',
  apiVersion: 'v2',
  pcVersion: 'v2',
  openapi: openapiSpec,
  site: 'acme-test',
  apiKey: 'test_api_key'
});

console.log(result.code); // Generated Node.js code string
console.log(result.language); // 'node-v3'

// Generate code for multiple languages
const allSamples = await generateCodeSamples({
  languages: ['curl', 'node-v3', 'python-v3', 'java'],
  resource: 'customer',
  operation: 'create_a_customer',
  apiVersion: 'v2',
  openapi: openapiSpec
});

console.log(allSamples['node-v3']); // Node.js code
console.log(allSamples['python-v3']); // Python code

// Or use pre-generated samples
const result = await generateCodeSample({
  language: 'python-v3',
  samples: {
    'python-v3': 'import chargebee\nchargebee.configure(...)'
  }
});

Use Cases:

• LLM/AI code generation tools
• Server-side code generation (SSG/SSR)
• CLI tools and scripts
• Non-React applications
• Testing and validation

Code Generators (Server-Side)

The code generators (getGenerator, extractOperationMetadataFromOpenAPI) are server-side only and require @cb-docs-platform/openapi-utils to be installed. If you're only using the React components (CodeSamples, CodeBlock), you don't need this dependency.

# If using generators (SSG/SSR)
pnpm add @cb-docs-platform/openapi-utils

Note: @cb-docs-platform/openapi-utils is currently a private package. If you need to use generators, ensure you have access to the Chargebee internal npm registry or install it from the monorepo.

License

MIT