@ coursebee/ code- sample- generator (英语)

一个自成一体,可再使用的React组件,用于显示API代码样本并带有语法突出,语言切换,和复制功能.

特征

• 显示组件: Renders 预生成的代码样本,带有美丽的语法突出
• 多语言: 支持12+语言(cURL, Node.js, Python, PHP, Ruby, Java,.NET, Go, TypeScript)
• 语法突出显示: 电源 志纪
• 特性- Rich: Carousel, 复制按钮, 动画, 语言切换器
• 浏览器导出: 用于代码生成的优化浏览器 API ()createCodeGenerator(中文(简体) )
• 批量生成: 为 SSG 构建高效的并行代码生成
• 结构错误: 自定义带有操作/语言背景的错误类
• 类型安全: 用于自动完成和验证的ID联盟类型
• 可主题: 可配置的主题和样式

安装

pnpm add @chargebee/code-sample-generator

反演 UI 消费者也必须安装 react, (中文(简体) ), react-dom,以及 lucide-react。 。 。 . 它们是可选的对等关系 如此无头 /node 消费者不安装 反应堆栈.

释放

生成的操作描述符在成为前被执行和审查 软件包释放的一部分。 包裹之后 fix 或者说 feat 更改合并, 发布请打开单独的版本并更改log拉请求. 合并那个 释放拉出请求将所审查的确切寄存器内容发布到 npm. 登记册披露该版本后,发布工作流程通知 充电蜂CLI调节器. 手册 version 输入可以安全地重新通知 在拖曳或恢复时已经发布的版本.

条目点

本套件有三个切入点:

使用 /browser 在客户端(反应)代码中,以及 /node 无头代码生成 (CLIs、SSG/SSR、LLM工具、节点/Deno/Bun)。 这个 /node 条目中没有反应或 DOM 依赖性。 主要条目包括Node.js内建(node:fs, (中文(简体) ), node:path)和React,因此不应直接用于浏览器构建.

构建时间突出显示( E)highlightCode(中文(简体) )

import { highlightCode } from '@chargebee/code-sample-generator/node';

const { html } = await highlightCode({
  code: 'const site = "acme-test";',
  language: 'javascript',
  showLineNumbers: true,
});
// html is dual-theme: tokens carry --shiki-light and --shiki-dark.
// The host `html.dark` class (cb-docs ThemeToggle) selects which set is visible.

<CodeBlock html={html} code={source} language="javascript" />

空着, plain 编号 : var 编号 : text,和未知的栅栏标签 解决了Shiki plaintext (主题面板,无关键词取色). 他们不扔.

文档标签( D)languageSwitcher: "tabs"(中文(简体) )

API Docs 省略此道具( 默认) "none")所以语言留在站点负责人SDK倒地. 用户文件通过 "tabs" 用于作者名的相片( label qq语法):

<CodeSamples
  features={{ languageSwitcher: "tabs", showHeader: false, showLineNumbers: true }}
  samples={{
    CURL: { code: `curl https://...`, language: "bash" },
    JQUERY: { code: `const express = require("express");`, language: "javascript" },
  }}
/>

支持的语言

使用量

简单使用( 代码字符串)

import { CodeSamples } from '@chargebee/code-sample-generator/browser';
import '@chargebee/code-sample-generator/dist/code-samples.css';

function MyPage() {
  return (
    <CodeSamples
      codeString={`curl https://your-site.chargebee.com/api/v2/customers \\
  -u test_api_key: \\
  -X POST \\
  -d "first_name=John&last_name=Doe"`}
      language="curl"
      theme="github-light"
      features={{
        copyButton: true,
        showLineNumbers: true,
      }}
    />
  );
}

多个预生成样本

import { CodeSamples } from '@chargebee/code-sample-generator/browser';
import '@chargebee/code-sample-generator/dist/code-samples.css';

function MyPage() {
  // Pre-generate samples using generateCodeSamples (see Pure Function API below)
  const samples = {
    'curl': 'curl https://...',
    'node-v3': 'const chargebee = new Chargebee({...})',
    'python-v3': 'import chargebee\nchargebee.configure(...)',
  };

  return (
    <CodeSamples
      samples={samples}
      initialLanguage="node-v3"
      theme="github-light"
      features={{
        carousel: true,
        copyButton: true,
        showLanguageSwitcher: true,
      }}
    />
  );
}

道具

特征配置

API 版本

生成代码样本时, 您需要指定版本信息 :

• apiVersion: 充电蜂 API 版本 ("v1" 或者说 "v2"(中文(简体) )
• pcVersion: 产品目录版本("v1" 或者说 "v2"(中文(简体) )
  • 使用 "v1" 用于产品目录 2.0 之前创建的网站
  • 使用 "v2" 用于启用产品目录 2.0的站点
  • 当怀疑时,使用 "v2" (默认)

这些版本的组合决定了使用哪种操作描述符:

• apiVersion="v1" • 用途 v1 业务
• apiVersion="v2" + 键 pcVersion="v1" • 用途 v2-pcv1 业务
• apiVersion="v2" + 键 pcVersion="v2" • 用途 v2-pcv2 操作(最常见的)

他们

暗/光模式由 theme 道具 :

• theme="github-dark" - 暗模式造型( 默认)
• theme="github-light" - 灯光模式造型

任意 什基主题 名称被支持。 主题影响:

• 语法突出显示颜色
• 标题和按钮样式
• 复制按钮外观

// Dark mode (default)
<CodeSamples samples={samples} theme="github-dark" />

// Light mode
<CodeSamples samples={samples} theme="github-light" />

// Custom Shiki theme
<CodeSamples samples={samples} theme="nord" />

附加组件和钩

对于高级用途,您可以导入子组件和钩子来构建自定义执行:

子组件

import {
  CodeBlock,           // Syntax-highlighted code display
  CodeSampleHeader,    // Header with title and copy button
  Carousel,            // Multi-sample navigation
  LanguageSwitcher     // Language dropdown
} from '@chargebee/code-sample-generator/browser';

// Use CodeBlock for simple code display
<CodeBlock 
  code="const x = 1;" 
  language="typescript" 
  theme="github-light" 
/>

自定义钩

import {
  useSampleLoader,      // Load and normalize samples
  useLanguageSelection   // Manage language state
} from '@chargebee/code-sample-generator/browser';

function MyCustomComponent() {
  const { samples, loading } = useSampleLoader({ /* ... */ });
  const { language, setLanguage } = useLanguageSelection();
  // ...
}

常数

import {
  AVAILABLE_LANGUAGES,  // List of supported languages
  DEFAULT_LANGUAGE,      // Default language ("curl")
  DEFAULT_THEME          // Default theme ("github-dark")
} from '@chargebee/code-sample-generator/browser';

建筑

• 发电机/:语言特有代码生成器(Go,Node.js,Python等)
• 元数据/: OpenAPI 元数据提取
• 组件/: 反应 UI 组件
• 样式/: CSS主题和动画

代码生成对显示

重要内容: 这个 CodeSamples 组件为 a 显示组件 - 它使预生成的代码串。 它不从OpenAPI specs生成代码.

从 OpenAPI 规格生成代码,使用 generateCodeSample 或者说 generateCodeSamples 函数(见下文纯函数 API),然后将结果传递给组件:

import { CodeSamples } from '@chargebee/code-sample-generator/browser';
import { generateCodeSamples } from '@chargebee/code-sample-generator/node';

// In your loader/server component (SSG/SSR)
export async function loader() {
  const samples = await generateCodeSamples({
    languages: ['curl', 'node-v3', 'python-v3'],
    operation: 'create_a_customer',
    apiVersion: 'v2',
    pcVersion: 'v2',
    site: 'acme-test',
    apiKey: '{site_api_key}',
    request: {
      uri: '/customers',
      method: 'POST',
      params: { first_name: 'John', last_name: 'Doe', email: '[email protected]' }
    }
  });

  return { samples };
}

// In your React component
function MyPage({ samples }) {
  return <CodeSamples samples={samples} />;
}

浏览器导出( Client- Side Generation)

对于需要动态生成代码的浏览器环境(如API Explorer操场),使用浏览器导出:

警卫: 永远不要在浏览器代码中放出真正的 Curgebee API 密钥, 生成 资产,或公共文件网站。 这个 apiKey 输入值 ; 使用占位符或有意的非秘密测试 数值。 此软件包生成代码- 它不认证 API 请求 .

基本设置

import { createCodeGenerator } from '@chargebee/code-sample-generator/browser';

// Create a generator instance (singleton pattern recommended)
const generator = createCodeGenerator({
  apiVersion: 'v2',
  pcVersion: 'v2',
  site: 'acme-test',
  apiKey: '{site_api_key}',
  cache: 'memory' // Only 'memory' or 'none' supported in browser
});

动态生成代码

// Generate code for a specific operation
const result = await generator.generate({
  language: 'curl',
  operation: 'create_a_customer',
  request: {
    params: { first_name: 'John', last_name: 'Doe', email: '[email protected]' }
  }
});

console.log(result.code); // Generated code string

反应组件示例( API 探索器)

import { useState, useEffect } from 'react';
import { createCodeGenerator } from '@chargebee/code-sample-generator/browser';

function CodeSamplePlayground({ operation, params }) {
  const [code, setCode] = useState('');
  const [language, setLanguage] = useState('curl');

  useEffect(() => {
    const generator = createCodeGenerator({
      apiVersion: 'v2',
      pcVersion: 'v2',
      site: 'acme-test',
      apiKey: '{site_api_key}',
    });

    // Generate code when params change
    generator.generate({
      language,
      operation,
      request: { params }
    }).then(result => {
      setCode(result.code);
    }).catch(error => {
      console.error('Failed to generate code:', error);
      setCode(`// Error: ${error.message}`);
    });
  }, [operation, params, language]);

  return (
    <div>
      <select value={language} onChange={e => setLanguage(e.target.value)}>
        <option value="curl">cURL</option>
        <option value="node-v3">Node.js</option>
        <option value="python-v3">Python</option>
      </select>
      <pre>{code}</pre>
    </div>
  );
}

预选操作

预设共同操作来为缓存加热以更快的后继生成:

const generator = createCodeGenerator({ /* ... */ });

// Prefetch operations on mount
await generator.prefetch('create_a_customer');
await generator.prefetch('list_customers');
await generator.prefetch('update_a_customer');

运行时间验证

在生成代码前运行时验证操作 ID :

import { validateOperationId, type OperationId } from '@chargebee/code-sample-generator/browser';

// Option 1: Type-safe from the start (if you know the operation)
const operation: OperationId = 'create_a_customer';
const result = await generator.generate<'create_a_customer'>({
  language: 'curl',
  operation, // ✅ Type-safe OperationId
  request: { 
    params: {
      first_name: 'John',  // ✅ Type-safe (if OperationParamsMap is extended)
      email: '[email protected]'
    }
  }
});

// Option 2: Runtime validation for user input
const userInput: string = getUserInput(); // From form, API, etc.
if (validateOperationId(userInput)) {
  // TypeScript now knows userInput is OperationId
  const result = await generator.generate({
    language: 'curl',
    operation: userInput, // ✅ Type-safe (validated OperationId)
    request: { 
      params: {
        first_name: 'John',
        email: '[email protected]'
      }
    }
  });
} else {
  console.error('Invalid operation ID:', userInput);
}

说明: 完全安全 request.params,您需要:

1. 使用通用类型参数 : generator.generate<'create_a_customer'>()
2. 扩展 OperationParamsMap 通过模块增强(见纯函数 API 部分)

处理错误

浏览器 API 扔出结构错误 :

import { 
  CodeGenerationError, 
  OperationNotFoundError, 
  LanguageNotSupportedError 
} from '@chargebee/code-sample-generator/browser';

try {
  const result = await generator.generate({ /* ... */ });
} catch (error) {
  if (error instanceof OperationNotFoundError) {
    console.error(`Operation not found: ${error.operation} for version ${error.version}`);
  } else if (error instanceof LanguageNotSupportedError) {
    console.error(`Language not supported: ${error.language}`);
    console.log(`Supported: ${error.supportedLanguages.join(', ')}`);
  } else if (error instanceof CodeGenerationError) {
    console.error(`Failed to generate ${error.language} code for ${error.operation}`);
    if (error.cause) {
      console.error('Cause:', error.cause);
    }
  }
}

说明: 过 openapi 或预取 descriptor 输入 createCodeGenerator 编号 : generate。内存缓存是可选的.

纯函数 API (Server-Side)

对于Node.js,LLMs,Deno,Bun,或服务器侧生成(SSG/SSR),使用纯函数 API:

import { generateCodeSample, generateCodeSamples } from '@chargebee/code-sample-generator/node';

// Generate code for a specific language (pass openapi or descriptor)
const result = await generateCodeSample({
  language: 'node-v3',
  operation: 'create_a_customer',
  apiVersion: 'v2',
  pcVersion: 'v2',
  site: 'acme-test',
  apiKey: '{site_api_key}',
  openapi, // host-supplied OpenAPI document
  request: {
    uri: '/customers',
    method: 'POST',
    params: { first_name: 'John', last_name: 'Doe', email: '[email protected]' }
  }
});

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-v3'],
  operation: 'create_a_customer',
  apiVersion: 'v2',
  pcVersion: 'v2',
  site: 'acme-test',
  apiKey: '{site_api_key}',
  openapi,
  request: {
    uri: '/customers',
    method: 'POST',
    params: { first_name: 'John', email: '[email protected]' }
  }
});

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

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

使用大小写 :

• LLM/AI 代码生成工具
• 服务器端代码生成( SSG/ SSR)
• CLI 工具和脚本
• 非反应应用程序
• 测试和验证

高级导出

代码生成器(服务器)

生成器需要 OpenAPI 文档或预取描述符 :

import {
  getGenerator,
  getSupportedLanguages,
  getSpecDescriptors,
  generateCodeSample,
} from '@chargebee/code-sample-generator/node';

// Get list of supported languages
const languages = getSupportedLanguages(); // ['curl', 'node-v3', 'python-v3', ...]

// Get generator for a specific language
const generator = getGenerator('node-v3');

// Resolve descriptors from your OpenAPI document
const descriptors = getSpecDescriptors(openapi);
const operation = descriptors.get('create_a_customer');

// Or pass openapi/descriptor into generateCodeSample
await generateCodeSample({ operation: 'create_a_customer', language: 'curl', openapi, /* ... */ });

类型出口

import type { 
  CodeSamplesPropsInterface,
  GenerateCodeSampleOptions,
  GenerateCodeSampleResult,
  Language,
  ApiVersion,
  OperationDescriptor,
  OperationId,              // Union type for all operation IDs
  V1OperationId,            // v1 operation IDs
  V2Pcv1OperationId,        // v2-pcv1 operation IDs
  V2Pcv2OperationId         // v2-pcv2 operation IDs (most common)
} from '@chargebee/code-sample-generator/node';

// Error classes
import {
  CodeGenerationError,
  OperationNotFoundError,
  LanguageNotSupportedError
} from '@chargebee/code-sample-generator/node';

帮助组件

import {
  GoToApiExplorer,    // Link to API Explorer
  TryInApiExplorer    // Button to try in API Explorer
} from '@chargebee/code-sample-generator/browser';

替换占位符

代码样本包支持替换站名和API密钥的占位符. 这对于:

• 构建时间替换: 在 SSG 构建时替换占位符
• 运行时间替换: 替换浏览器/客户端代码中的占位符

位置持有人如何工作

默认情况下,生成的代码包含诸如 {site} 财务报告和审定财务报表 {site_api_key}数字 :

curl https://{site}.chargebee.com/api/v2/customers \
  -u {site_api_key}:

构建时间替换( SSG)

在装入器/服务器组件中,用占位符生成代码,然后替换:

import { generateCodeSamples } from '@chargebee/code-sample-generator/node';

// Generate with placeholders
const samples = await generateCodeSamples({
  languages: ['curl', 'node-v3'],
  operation: 'create_a_customer',
  site: '{site}',           // Placeholder
  apiKey: '{site_api_key}', // Placeholder
  // ...
});

// Replace at build time if needed
const replacedSamples = Object.fromEntries(
  Object.entries(samples).map(([lang, code]) => [
    lang,
    code.replace(/{site}/g, 'acme-test').replace(/{site_api_key}/g, 'test_key')
  ])
);

运行时间替换( 组件)

使用 replacements 道具装入 CodeSamples 组件 :

<CodeSamples
  samples={samples}
  replacements={{
    '{site}': 'acme-test',
    '{site_api_key}': 'test_api_key'
  }}
/>

常见的占位符

何时使用替换

• 保留占位符: 当用户需要手动替换时(文档)
• 在构建时替换: 当生成带有示例值的静态文件时
• 运行时替换: 仅带有占位符或有意的非秘密测试值; 绝不在浏览器代码中披露真实的 API 密钥

批量生成 API( SSG)

为在 SSG 构建期间高效生成代码, 请使用批次 API :

import { generateCodeSamplesBatch } from '@chargebee/code-sample-generator/node';

// Generate code for multiple samples and languages in parallel
const results = await generateCodeSamplesBatch({
  samples: [
    { 
      name: "Create with card", 
      sample: { 
        uri: "/customers", 
        method: "POST", 
        params: { first_name: "John" } 
      } 
    },
    { 
      name: "Create with token", 
      sample: { 
        uri: "/customers", 
        method: "POST", 
        params: { payment_method: { type: "card" } } 
      } 
    }
  ],
  languages: ["curl", "node-v3", "python-v3", "java-v3"],
  config: {
    apiVersion: "v2",
    pcVersion: "v2",
    operation: "create_a_customer",
    site: "{site}",
    apiKey: "{site_api_key}"
  }
});

// Results format matches API docs loader expectations
results.forEach(result => {
  console.log(result.displayName);        // "Create with card"
  console.log(result.languageSnippets);  // { curl: "...", node-v3: "...", ... }
});

这比依次生成代码更为有效,特别是在为许多语言和样本变化生成代码时.

发展和描述刷新

操作说明 src/generated/ops/ 被执行所以 API 更改 软件包的发布可以核实其投入。 普通软件包 或 单曲 构建 编译已执行的描述符而不重写 跟踪源文件.

将仅结构的 OpenAPI 规格放入后 packages/openapi-utils/oas/,明确刷新描述 单列波根 :

pnpm refresh:code-sample-ops

下载新光谱的 CI 任务可以使用 build:from-specs 来刷新和 将软件包编译成一个命令 :

pnpm --filter @chargebee/code-sample-generator build:from-specs

进行OpenAPI驱动生成的测试需要这些已准备好的投入. 剥去规格后, 运行明确的准备和测试命令 :

pnpm --filter @chargebee/code-sample-generator test:from-specs

这个 Update OpenAPI Descriptors 工作流程按时间表进行此更新, 或何时 cb-openapi-generator 发送 openapi-specs-published 寄存器发送事件。 它打开或更新一个 PR 只有当生成的描述符不同时。 它交换 DISTRIBUTED_GITFLOW_GH_APP_CREDENTIALS_TOKEN 短暂的秘密 来自分布式- gitflow GitHub App 的安装令牌。 App 标志 创建分支和 PR , 这样寄存器的正常拉请求工作流程 运行生成的更新.

许可证

这套软件包的使用由《最终用户许可证协议》规定。 来源 代码仍然是Chargebee Inc的自有财产。 见 自由主义 全部条件.

如本报告所述,私下报告脆弱性 警卫。 。 。 .