@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

核心组件

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