Skip to content

Commit f4969fa

Browse files
dengzhaofunclaude
dengzhaofun
and
claude
authored
feat(docs): fumadocs-openapi 自动 API 参考 + 修好 /openapi.json + Scalar 鉴权 (#48)
* feat(docs): /docs 接入 fumadocs-openapi 自动 API 参考 + 修好 /openapi.json + Scalar 鉴权 server - 修复 /openapi.json 500:level 模块的 UnlockRuleSchema 用 z.lazy 做自递归但没注册成 component,zod-to-openapi 的 isOptionalSchema 走到它就栈溢出;加 .openapi("LevelUnlockRule") 把递归节点序列化成 $ref,文档恢复 200 (459 ops, 427 schemas)。 - 新 src/lib/openapi.ts 收拢三件事: - validationDefaultHook 统一 Zod 校验失败的 400 响应 {error,code:"VALIDATION_ERROR",issues,requestId} - createAdminRouter / createClientRouter / createPublicRouter 给每个模块 router 注入 defaultHook - createAdminRoute / createClientRoute / createPublicRoute 自动派生 operationId (${tag}_${method}_${path}) 并注入 security (Session+AdminApiKey / ClientCredential / []) - registerSecuritySchemes 在 app 层注册 Session / AdminApiKey / ClientCredential 三套 securitySchemes - 全部 30 个 admin routes.ts + 24 个 client-routes.ts + health.ts 机械化迁到新 helper;459/459 op 拿到唯一 operationId,admin/client/public security 数组按路由类型正确落位。 - index.ts 的 doc31 补 info.description(中文鉴权说明)。 - 新 pnpm --filter=server openapi:dump 把 spec 冻结到 apps/server/openapi.json,同时注入顶层 tags 数组(fumadocs-openapi 的 fromTagName 必需,否则直接崩)。 admin - pnpm --filter=admin gen:api-docs (bun 跑) 从 apps/server/openapi.json 生成中文 API 参考 MDX: - 自定义 groupBy 函数按 MODULES 前缀表折叠两层目录(Lottery→pools/tiers/prizes/pity-rules/pull/client,Entity→schemas/blueprints/skins/formations/client,etc) - 自动生成 index.mdx 落地页(Operations / Tags / Schemas 统计 + 鉴权速览 + 怎么用) - polishLeafMetas 修 leaf meta.json title(Lottery/Pools→Pools),给父文件夹补 meta.json,改写根 meta.json pages 让 fumadocs source loader 能找到。 - 新 src/lib/openapi.tsx:TanStack Start 没有 RSC,fumadocs-openapi 默认的 createAPIPage 是 async server component 会 hydrate 报错;换 createClientAPIPage 并把 MDX 里的 document="apollokit" 逻辑 key 映射到 bundled payload,spec 通过 ../../server/openapi.json 被 Vite import 进 bundle,运行期零 fetch。 - routes/docs/$.tsx 把 APIPage 注入 MDX components 映射。 - 顶部 nav links 改成 getBaseOptions(locale) 工厂,OpenAPI 入口跟随当前 locale(英文站点击不再被甩到 /docs/zh/api);Home / Dashboard 标签按 locale 切中英。 - content/docs/{zh,en}/meta.json 各加 API 参考 / API Reference 分组;zh 挂完整 api 子树,en 为了避免 MDX 文件数翻倍(vite/cf-vite-plugin 会 hang)只放单文件 api.mdx stub,内部链到中文版,依靠 fumadocs i18n fallback 让 en sidebar 也能看到 86 个模块。 - zh 的 folder title / index title 故意用通用英文(API / API Overview),因为 fumadocs i18n fallback 会把 zh 的 meta 直接当 en 的用,写中文会漏到英文站。 日常流程 pnpm dev # wrangler 在 8787 pnpm --filter=server openapi:dump # 刷快照 pnpm --filter=admin gen:api-docs # 重跑 MDX Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com> * chore(deps): refresh pnpm lockfile after fumadocs-openapi + shiki install Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com> --------- Co-authored-by: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
1 parent bf6f5c0 commit f4969fa

633 files changed

Lines changed: 75174 additions & 589 deletions

File tree

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.

‎apps/admin/content/docs/en/api.mdx‎

Lines changed: 18 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,18 @@
1+
---
2+
title: API Reference
3+
description: Auto-generated OpenAPI reference (currently Chinese-only).
4+
---
5+
6+
The full API reference is auto-generated from `apps/server/openapi.json` and currently lives under the **Chinese** locale only. Operation summaries / descriptions in the spec are not yet translated into English, so we ship a single source of truth.
7+
8+
→ [Open the API reference (中文)](/docs/zh/api)
9+
10+
## What's there
11+
12+
- **459 operations** across 86 tags (Lottery, Shop, Check-In, Storage Box, …)
13+
- Per-operation playground (Send button) wired to your local server
14+
- `Authorization` block per route showing which credential the route accepts (Session cookie / `ak_…` / `cpk_…` + HMAC)
15+
- 6-language code samples (cURL / JavaScript / Go / Python / Java / C#)
16+
- Full response schemas for every declared status code (200/400/401/404/409)
17+
18+
When the spec gains real bilingual descriptions, the generator (see `apps/admin/scripts/generate-api-docs.ts`) will emit `content/docs/en/api/` and this stub will be deleted.

‎apps/admin/content/docs/en/meta.json‎

Lines changed: 3 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -44,6 +44,8 @@
4444
"---Integration---",
4545
"webhooks",
4646
"client-sdk",
47-
"sdk"
47+
"sdk",
48+
"---API Reference---",
49+
"api"
4850
]
4951
}

‎apps/admin/content/docs/zh/api/activity/activity_delete_by_id.mdx‎

Lines changed: 14 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,14 @@
1+
---
2+
title: Delete an activity
3+
full: true
4+
_openapi:
5+
method: DELETE
6+
toc: []
7+
structuredData:
8+
headings: []
9+
contents: []
10+
---
11+
12+
{/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */}
13+
14+
<APIPage document={"apollokit"} operations={[{"path":"/api/activity/{id}","method":"delete"}]} />

‎apps/admin/content/docs/zh/api/activity/activity_delete_nodes_by_id.mdx‎

Lines changed: 14 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,14 @@
1+
---
2+
title: Delete an activity node
3+
full: true
4+
_openapi:
5+
method: DELETE
6+
toc: []
7+
structuredData:
8+
headings: []
9+
contents: []
10+
---
11+
12+
{/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */}
13+
14+
<APIPage document={"apollokit"} operations={[{"path":"/api/activity/nodes/{id}","method":"delete"}]} />

‎apps/admin/content/docs/zh/api/activity/activity_delete_schedules_by_id.mdx‎

Lines changed: 14 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,14 @@
1+
---
2+
title: Delete a schedule
3+
full: true
4+
_openapi:
5+
method: DELETE
6+
toc: []
7+
structuredData:
8+
headings: []
9+
contents: []
10+
---
11+
12+
{/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */}
13+
14+
<APIPage document={"apollokit"} operations={[{"path":"/api/activity/schedules/{id}","method":"delete"}]} />

‎apps/admin/content/docs/zh/api/activity/activity_delete_templates_by_id.mdx‎

Lines changed: 14 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,14 @@
1+
---
2+
title: Delete an activity template.
3+
full: true
4+
_openapi:
5+
method: DELETE
6+
toc: []
7+
structuredData:
8+
headings: []
9+
contents: []
10+
---
11+
12+
{/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */}
13+
14+
<APIPage document={"apollokit"} operations={[{"path":"/api/activity/templates/{id}","method":"delete"}]} />

‎apps/admin/content/docs/zh/api/activity/activity_delete_webhook_endpoints_by_id.mdx‎

Lines changed: 14 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,14 @@
1+
---
2+
title: Delete a webhook endpoint
3+
full: true
4+
_openapi:
5+
method: DELETE
6+
toc: []
7+
structuredData:
8+
headings: []
9+
contents: []
10+
---
11+
12+
{/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */}
13+
14+
<APIPage document={"apollokit"} operations={[{"path":"/api/activity/webhook-endpoints/{id}","method":"delete"}]} />

‎apps/admin/content/docs/zh/api/activity/activity_get_by_key.mdx‎

Lines changed: 14 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,14 @@
1+
---
2+
title: Fetch an activity by id or alias
3+
full: true
4+
_openapi:
5+
method: GET
6+
toc: []
7+
structuredData:
8+
headings: []
9+
contents: []
10+
---
11+
12+
{/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */}
13+
14+
<APIPage document={"apollokit"} operations={[{"path":"/api/activity/{key}","method":"get"}]} />

‎apps/admin/content/docs/zh/api/activity/activity_get_by_key_analytics.mdx‎

Lines changed: 14 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,14 @@
1+
---
2+
title: Participation stats for an activity.
3+
full: true
4+
_openapi:
5+
method: GET
6+
toc: []
7+
structuredData:
8+
headings: []
9+
contents: []
10+
---
11+
12+
{/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */}
13+
14+
<APIPage document={"apollokit"} operations={[{"path":"/api/activity/{key}/analytics","method":"get"}]} />

‎apps/admin/content/docs/zh/api/activity/activity_get_by_key_nodes.mdx‎

Lines changed: 14 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,14 @@
1+
---
2+
title: List nodes of an activity
3+
full: true
4+
_openapi:
5+
method: GET
6+
toc: []
7+
structuredData:
8+
headings: []
9+
contents: []
10+
---
11+
12+
{/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */}
13+
14+
<APIPage document={"apollokit"} operations={[{"path":"/api/activity/{key}/nodes","method":"get"}]} />

0 commit comments

Comments
 (0)