@pontx/shadcn-ui

基于 Shadcn UI + Radix UI 构建的 API 文档与调试组件库，提供开箱即用的 API 文档展示、接口目录、Schema 查看、在线调试等功能。

安装

npm install @pontx/shadcn-ui
# or
pnpm add @pontx/shadcn-ui

Peer Dependencies

npm install react react-dom

核心组件

统一设计系统

样式入口包含一套与 Shadcn 兼容的语义令牌。业务页面应优先使用语义色，避免直接写 gray-*、green-* 或任意品牌色：

/* 可在应用根节点覆盖，值使用 HSL 通道。 */
:root {
  --primary: 221 83% 53%;
  --background: 216 33% 97%;
  --foreground: 222 47% 11%;
  --border: 214 27% 88%;
  --success: 160 70% 31%;
  --warning: 32 95% 44%;
  --radius: 0.625rem;
}

基础组件从主入口导出：

import {
  Alert,
  Badge,
  Button,
  Card,
  EmptyState,
  Input,
  MethodBadge,
  Select,
  StatusBadge,
  Tabs,
} from "@pontx/shadcn-ui";

<Card variant="elevated">
  <MethodBadge method="GET" />
  <StatusBadge status="success">HTTP 200</StatusBadge>
  <Button size="sm">执行</Button>
</Card>;

• Button：default、secondary、outline、subtle、ghost、destructive。
• Card：default、elevated、muted、flat。
• Badge：中性、品牌、成功、警告、信息和错误状态。
• MethodBadge：统一 GET、POST、PUT、PATCH、DELETE 等 HTTP 方法色。
• StatusBadge、Alert、EmptyState：统一结果反馈、提示和空状态。

API 目录、文档、Schema 与 Playground 已共享这些令牌和组件。集成页面可在外层添加 data-pontx-ui，以获得统一字体、滚动条和可访问性基线。

ApiDocumentation - API 文档

展示单个 API 的完整文档，包含参数说明、请求/响应 Schema、在线调试面板。

import { ApiDocumentation } from "@pontx/shadcn-ui/api-documentation";
import "@pontx/shadcn-ui/styles";

<ApiDocumentation
  api={apiData}
  enablePlayground
  specName="my-api"
  servers={[{ url: "https://api.example.com" }]}
  onExecute={(request) => fetch(request.url, { method: request.method })}
/>;

ApiDirectory - API 目录

以分组形式展示 API 列表，支持搜索和筛选。

import { ApiDirectory } from "@pontx/shadcn-ui/api-directory";

<ApiDirectory
  spec={pontxSpec}
  selectedApiName="getUser"
  onApiSelect={(name, api, tag) => console.log(name)}
  showMethod
  searchPlaceholder="搜索 API..."
/>;

SchemaViewer - Schema 查看器

可视化展示 JSON Schema 结构。

import { SchemaViewer } from "@pontx/shadcn-ui/schema-viewer";

<SchemaViewer schema={jsonSchema} />;

PlaygroundPanel - 在线调试面板

API 请求调试面板，支持参数填写、鉴权配置、请求发送、响应展示和代码生成。

import { PlaygroundPanel } from "@pontx/shadcn-ui/playground";

<PlaygroundPanel
  api={apiData}
  servers={servers}
  onExecute={handleExecute}
  executionResult={result}
  isExecuting={loading}
/>;

DebugPanel - 调试面板

import { DebugPanel } from "@pontx/shadcn-ui/debug-panel";

PontxApp - 完整应用

一站式 API 文档 SPA，集成目录、文档、调试等全部功能。

import { PontxApp } from "@pontx/shadcn-ui";

<PontxApp
  spec={pontxSpec}
  getCodeGenScenarios={() => [
    { id: "curl", label: "cURL", language: "shell" },
    { id: "typescript", label: "TypeScript", language: "typescript" },
  ]}
  onGenerateCode={({ scenarioId, request }) => generateCode(scenarioId, request)}
/>;

也可以直接使用预构建的 HTML 页面：

@pontx/shadcn-ui/app → dist/app/app.html

样式引入

使用组件前需要引入样式文件：

import "@pontx/shadcn-ui/styles";

导出路径

| 路径 | 说明 | | --------------------------------- | --------------- | | @pontx/shadcn-ui | 全量导出 | | @pontx/shadcn-ui/api-documentation | API 文档组件 | | @pontx/shadcn-ui/api-directory | API 目录组件 | | @pontx/shadcn-ui/schema-viewer | Schema 查看器 | | @pontx/shadcn-ui/debug-panel | 调试面板 | | @pontx/shadcn-ui/playground | Playground 组件 | | @pontx/shadcn-ui/styles | 样式文件 | | @pontx/shadcn-ui/app | 预构建 HTML 应用 |

鉴权支持

内置多种鉴权方式：

• API Key - 支持 header / query / cookie
• Bearer Token
• Basic Auth
• OAuth2

技术栈

• React 18 / 19
• TypeScript
• TailwindCSS
• Radix UI
• Monaco Editor
• @pontx/spec

License

MIT