535dc86a7a
feat(migrate): port ApiReference (Scalar-style) to React workspace package
...
Sprint 2 §S6. Ports legacy `docs/.vitepress/theme/components/ApiReference.vue`
(1370 lines) to React inside a new `packages/api-reference` workspace
published as `@longbridge/openapi-api-reference`. Zero use of
`@scalar/*` or any third-party OpenAPI viewer — this is a manual 1:1 port.
Match legacy behaviour:
- Hash routing via `?op=<epId>` and `?page=<pageId>` + popstate listener
- Three views: intro / page / endpoint
- Sidebar with search + tag groups + method-color badges (GET/POST/PUT/DELETE)
- markdown-it prose rendering + external-link renderer patch
- Schema tree walker with `$ref` resolution + envelope detection
- Code-sample tabs (JS/Python/Rust/Java/Go/C++) via inline regex highlighter
- `QuotePermission` badge sourced from `quote-permissions.yaml`
- Locale-aware doc-link rewrites (`localizeDocLinks`)
- Dark mode double-guard `[data-theme="dark"]` + `prefers-color-scheme`
Files created:
- `packages/api-reference/package.json` — bun workspace, deps js-yaml + markdown-it
- `packages/api-reference/tsconfig.json` — extends root, includes .astro types
- `packages/api-reference/src/index.ts` — barrel
- `packages/api-reference/src/openapi-loader.ts` — yaml.load + $ref resolver
- `packages/api-reference/src/ApiReference.tsx` — top-level CSR component
- `packages/api-reference/src/CodeSample.tsx` — code panel + syntax highlight
- `packages/api-reference/src/QuotePermission.tsx` — permissions badge
- `packages/api-reference/src/api-reference.css` — 280px sidebar + fluid main +
440px code panel + method colors + dark-mode
Files modified:
- `src/layouts/ApiReferenceLayout.astro` — mounts <ApiReference client:load
rawYaml={rawYaml} locale={locale} /> with the CSS import (needed subpath in
the package's `exports` field to resolve the CSS through the workspace name)
- `src/data/locale.{en,zh-CN,zh-HK}.ts` — api.* keys (search, section labels,
copy states, intro copy, param labels, fallback, pathCopy)
- `src/mdx-components.tsx` — remove dead ApiReference entry (mounted via
layout, not mdx tag)
- root `package.json` — workspace dep `@longbridge/openapi-api-reference`
Files deleted:
- `src/components/mdx/placeholders/ApiReference.tsx`
Runtime bugfix (post-subagent): package.json `exports` field only exposed
`.` and rejected `./src/api-reference.css` subpath, throwing a 500 on every
route once the layout tried to import the CSS. Added the CSS subpath to
`exports`. All 15 canonical URLs return 200 after fix.
Verified:
- astro check: 0 errors (85 files)
- /docs/api renders with sidebar (Overview / Real-Time Market Data / Error
Codes + tag groups Watchlist Management / Market Temperature / Portfolio
& Cash / News & Filings + method-color badges) + intro cards
(REST API / WebSocket) — screenshot in gate/s6-verify-api.png
- /zh-CN/docs/api, /zh-HK/docs/api, /docs/quote/overview all 200
- `data-lbus-component` on api-reference / api-sidebar / api-intro
Closes Sprint 2 §S6 (gate finding A13 / A14).
Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com >
2026-08-19 01:00:50 +08:00
twosugar