feat(api-docs): 展示请求 body 格式

- 为 POST/PATCH 端点添加可展开的 body 示例

Author: GoJam11

console/ai-proxy-dashboard/src/features/dashboard/components/api-docs-page.tsx

@@ -3,36 +3,99 @@ import { Card, CardContent, CardDescription, CardHeader, CardTitle } from "@/com
 import { Badge } from "@/components/ui/badge"
 import { Button } from "@/components/ui/button"
 import { Input } from "@/components/ui/input"
-import { Copy, Check } from "lucide-react"
+import { Copy, Check, ChevronDown, ChevronRight } from "lucide-react"
 
 interface Endpoint {
   method: string
   path: string
   description: string
   auth: boolean
+  body?: BodyExample
+}
+
+interface BodyExample {
+  description: string
+  json: unknown
+}
+
+const PROVIDER_BODY: BodyExample = {
+  description: "创建/更新渠道",
+  json: {
+    channelName: "my-openai",
+    type: "openai",
+    targetBaseUrl: "https://api.openai.com/v1",
+    systemPrompt: null,
+    models: ["gpt-4o", "gpt-4o-mini"],
+    priority: 100,
+    auth: {
+      header: "authorization",
+      value: "sk-xxxx"
+    },
+    responsesMode: "native",
+    extraFields: null
+  }
+}
+
+const PROVIDER_ENABLED_BODY: BodyExample = {
+  description: "启用/禁用渠道",
+  json: {
+    enabled: true
+  }
+}
+
+const KEY_NAME_BODY: BodyExample = {
+  description: "创建/重命名 API Key",
+  json: {
+    name: "my-key"
+  }
+}
+
+const KEY_MODELS_BODY: BodyExample = {
+  description: "设置允许模型列表",
+  json: {
+    models: ["gpt-4o", "gpt-4o-mini"]
+  }
+}
+
+const ALIAS_BODY: BodyExample = {
+  description: "创建/更新模型别名",
+  json: {
+    alias: "gpt-4o",
+    provider: "my-openai",
+    model: "gpt-4o-2024-08-06",
+    description: "GPT-4o 主力模型",
+    enabled: true
+  }
+}
+
+const ALIAS_ENABLED_BODY: BodyExample = {
+  description: "启用/禁用模型别名",
+  json: {
+    enabled: true
+  }
 }
 
 const ENDPOINTS: Endpoint[] = [
   { method: "GET", path: "/api/v1/health", description: "健康检查", auth: false },
   { method: "GET", path: "/api/v1/providers", description: "获取所有渠道", auth: true },
   { method: "GET", path: "/api/v1/providers/:channelName", description: "获取单个渠道详情", auth: true },
-  { method: "POST", path: "/api/v1/providers", description: "创建渠道", auth: true },
-  { method: "PATCH", path: "/api/v1/providers/:channelName", description: "更新渠道", auth: true },
+  { method: "POST", path: "/api/v1/providers", description: "创建渠道", auth: true, body: PROVIDER_BODY },
+  { method: "PATCH", path: "/api/v1/providers/:channelName", description: "更新渠道", auth: true, body: PROVIDER_BODY },
   { method: "DELETE", path: "/api/v1/providers/:channelName", description: "删除渠道", auth: true },
-  { method: "PATCH", path: "/api/v1/providers/:channelName/enabled", description: "启用/禁用渠道", auth: true },
+  { method: "PATCH", path: "/api/v1/providers/:channelName/enabled", description: "启用/禁用渠道", auth: true, body: PROVIDER_ENABLED_BODY },
   { method: "GET", path: "/api/v1/requests", description: "获取请求日志列表", auth: true },
   { method: "GET", path: "/api/v1/requests/:requestId", description: "获取单个请求详情", auth: true },
   { method: "GET", path: "/api/v1/stats", description: "获取统计数据", auth: true },
   { method: "GET", path: "/api/v1/keys", description: "获取所有 API Keys", auth: true },
   { method: "GET", path: "/api/v1/keys/:id", description: "获取单个 API Key", auth: true },
-  { method: "POST", path: "/api/v1/keys", description: "创建 API Key", auth: true },
-  { method: "PATCH", path: "/api/v1/keys/:id", description: "重命名 API Key", auth: true },
+  { method: "POST", path: "/api/v1/keys", description: "创建 API Key", auth: true, body: KEY_NAME_BODY },
+  { method: "PATCH", path: "/api/v1/keys/:id", description: "重命名 API Key", auth: true, body: KEY_NAME_BODY },
   { method: "DELETE", path: "/api/v1/keys/:id", description: "删除 API Key", auth: true },
-  { method: "PATCH", path: "/api/v1/keys/:id/allowed-models", description: "设置 API Key 允许模型", auth: true },
+  { method: "PATCH", path: "/api/v1/keys/:id/allowed-models", description: "设置 API Key 允许模型", auth: true, body: KEY_MODELS_BODY },
   { method: "GET", path: "/api/v1/aliases", description: "获取所有模型别名", auth: true },
-  { method: "POST", path: "/api/v1/aliases", description: "创建模型别名", auth: true },
-  { method: "PATCH", path: "/api/v1/aliases/:id", description: "更新模型别名", auth: true },
-  { method: "PATCH", path: "/api/v1/aliases/:id/enabled", description: "启用/禁用模型别名", auth: true },
+  { method: "POST", path: "/api/v1/aliases", description: "创建模型别名", auth: true, body: ALIAS_BODY },
+  { method: "PATCH", path: "/api/v1/aliases/:id", description: "更新模型别名", auth: true, body: ALIAS_BODY },
+  { method: "PATCH", path: "/api/v1/aliases/:id/enabled", description: "启用/禁用模型别名", auth: true, body: ALIAS_ENABLED_BODY },
   { method: "DELETE", path: "/api/v1/aliases/:id", description: "删除模型别名", auth: true },
 ]
 
@@ -64,6 +127,41 @@ function CopyButton({ text }: { text: string }) {
   )
 }
 
+function EndpointItem({ ep }: { ep: Endpoint }) {
+  const [expanded, setExpanded] = useState(false)
+
+  return (
+    <div className="rounded-md border">
+      <div
+        className="flex items-center gap-3 p-3 hover:bg-muted/50 cursor-pointer select-none"
+        onClick={() => ep.body && setExpanded((v) => !v)}
+      >
+        <MethodBadge method={ep.method} />
+        <code className="flex-1 text-sm font-mono">{ep.path}</code>
+        <span className="text-sm text-muted-foreground">{ep.description}</span>
+        {ep.auth && <Badge variant="outline" className="text-xs">需认证</Badge>}
+        {ep.body && (
+          expanded
+            ? <ChevronDown className="h-4 w-4 text-muted-foreground" />
+            : <ChevronRight className="h-4 w-4 text-muted-foreground" />
+        )}
+      </div>
+
+      {expanded && ep.body && (
+        <div className="border-t px-3 py-3 space-y-2">
+          <div className="flex items-center justify-between">
+            <span className="text-xs text-muted-foreground">{ep.body.description} - Request Body</span>
+            <CopyButton text={JSON.stringify(ep.body.json, null, 2)} />
+          </div>
+          <pre className="rounded-md bg-muted p-3 text-xs font-mono overflow-x-auto">
+            <code>{JSON.stringify(ep.body.json, null, 2)}</code>
+          </pre>
+        </div>
+      )}
+    </div>
+  )
+}
+
 export function ApiDocsPage() {
   const [filter, setFilter] = useState("")
 
@@ -117,15 +215,7 @@ export function ApiDocsPage() {
         <CardContent>
           <div className="flex flex-col gap-2">
             {filtered.map((ep) => (
-              <div
-                key={ep.path + ep.method}
-                className="flex items-center gap-3 rounded-md border p-3 hover:bg-muted/50"
-              >
-                <MethodBadge method={ep.method} />
-                <code className="flex-1 text-sm font-mono">{ep.path}</code>
-                <span className="text-sm text-muted-foreground">{ep.description}</span>
-                {ep.auth && <Badge variant="outline" className="text-xs">需认证</Badge>}
-              </div>
+              <EndpointItem key={ep.path + ep.method} ep={ep} />
             ))}
           </div>
         </CardContent>