Skip to content

fix(api-reference): de-duplicate API page titles and descriptions - #1335

Merged
twosugar merged 1 commit into
mainfrom
fix/api-reference-duplicate-meta
Nov 19, 2026
Merged

twosugar merged 1 commit into
mainfrom
fix/api-reference-duplicate-meta

Conversation

@twosugar

Copy link
Copy Markdown
Collaborator

Merge Verdict

[APPROVE]

1 file · +19 / -19 · copy-only change to openapi.yaml, no code touched

Summary

Several API Reference pages shared the same <title> or meta description, which search engines treat as duplicate pages and which also misdescribed some endpoints. This PR fixes the copy in openapi.yaml only:

Pages Before After
ws-push-depth / ws-push-trade / ws-push-candlestick (en) Depth / Trades / Candlesticks, same as the pull commands Depth Subscription / Trades Subscription / Candlesticks Subscription
ws-push-candlestick (zh-CN / zh-HK) K 线 / K 線, same as pull 实时 K 线订阅 / K 線訂閱, matching the other push commands (实时盘口订阅 / 盤口訂閱)
fund_positions (zh-CN / zh-HK) 基金持仓 / 基金持倉, same as fund_holdings 账户基金持仓 / 賬戶基金持倉
short_positions_hk / short_positions_us (3 locales) Both said "US or HK, auto-detected by symbol suffix" Each describes its own market and update cadence
short_trades_hk / short_trades_us (3 locales) Both said "supports US and HK" Each describes its own market and update cadence

Update cadences (daily / bi-monthly / each trading day / bi-weekly) are carried over unchanged from the original text.

Risk Analysis

Risk Level Mitigation
Push command names also appear in the left nav and site search, so en users now see … Subscription there Low Intended: it is what distinguishes them from the pull commands
YAML breakage Low Only scalar values on existing lines changed; file parses with js-yaml

Design Decisions

  • English push names get a Subscription suffix rather than renaming the pull side, so existing pull page titles stay stable.
  • Chinese push naming follows the pattern the other push commands already use.

Code Concerns

[FYI] symbol parameter text on the four short-selling endpoints still mentions both markets (openapi.yaml, x-parameters of short_positions_hk/us, short_trades_hk/us): it still reads "e.g. TSLA.US or 700.HK" on each market-specific endpoint. Out of scope for this copy fix; can be aligned in a follow-up.

Verification

Conclusion basis: Verified

  • Recomputed title/description for all 483 API pages in 3 locales with apiPageMeta (the same function the pages use): 13 duplicate groups before, 0 after.
  • bun test in packages/api-reference: 10 pass, 0 fail.
  • Deployed to canary; spot-checked the changed pages on both open-canary.longbridge.xyz (11 pages) and open.longbridge.xyz (5 pages, all 3 locales): new titles and descriptions are served.

🤖 Generated with Claude Code

- WS push depth/trades/candlesticks: add "Subscription" so they no longer share titles with the pull commands
- fund_positions: zh title 账户基金持仓, distinct from fund_holdings
- short_positions_hk/us, short_trades_hk/us: describe each endpoint's own market

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
@twosugar
twosugar merged commit ae3ba97 into main Nov 19, 2026
2 checks passed
@twosugar
twosugar deleted the fix/api-reference-duplicate-meta branch November 19, 2026 05:36
twosugar pushed a commit that referenced this pull request Nov 19, 2026
…scription, add hreflang (#1337)

## Summary

Each API Reference page (`/docs/api/<id>`) has the same H1, the same
meta description and a title that only differs in the suffix from the
docs page for the same endpoint (e.g. `/docs/market/top-movers`). Google
Search Console shows that for 5 English pairs only one page of each pair
is indexed and the other is "Crawled - currently not indexed". API pages
also output no hreflang at all.

Both pages should stay (the docs page covers CLI / SDK usage, the API
page the HTTP request and Try it), so this PR only changes the `<head>`
of API pages:

| Change | File | Effect |
|---|---|---|
| Title and description carry the HTTP method and path; WebSocket
commands use `WebSocket cmd N` |
`packages/api-reference/src/openapi-markdown.ts` (`apiPageMeta()`) |
`Top Movers · API Reference` → `Top Movers (POST
/v1/quote/market/stock-events) · API Reference`; description becomes
`POST /v1/quote/market/stock-events — Get stocks whose…`. Same 160-char
truncation as before, the prefix is always kept. |
| API page URLs added to the published URL set |
`src/lib/published-urls.ts`, new `src/lib/api-page-urls.ts` |
`BaseLayout` already emits hreflang via `buildSeoLinks()`, but only for
URLs in `getPublishedUrls()`, which listed the docs collection only. API
pages (161 × 3 locales) now get `en` / `zh-Hans` / `zh-Hant` /
`x-default`, the same output as docs pages. No layout change. |
| Tests | `packages/api-reference/src/api-page-meta.test.ts`,
`src/lib/api-page-urls.test.ts` | label in every title/description, ≤160
chars, no duplicates among API pages per locale; three-locale hreflang
for an API page. |

Not in this PR (optional, your call): the H1 (`ep-title` in
`ApiReference.tsx`) is still the bare summary, e.g. `Top Movers`, same
as the docs page H1. Adding the method/path there would change what
users see on the page, so I left it out.

## Verification (before merge)

- Duplicate check with `apiPageMeta` (same method as #1335), 483 API
pages vs 866 docs pages, same locale:

  | | before | after |
  |---|---|---|
  | duplicate titles among API pages | 0 | 0 |
  | duplicate descriptions among API pages | 0 | 0 |
  | API page title (without suffix) = docs page title | 347 | 0 |
  | API page description = docs page description | 317 | 0 |

- `astro dev`, `<head>` of the 6 pairs below: all 200, title and
description differ within each pair, canonical self-referencing, each
API page has 4 hreflang links pointing to its own en / zh-CN / zh-HK
URLs + x-default (also checked `/zh-CN/docs/api/top_movers`).
- `vitest run`: 72/72 passed (8 files). `bun test` in
`packages/api-reference`: 20/20.
- `oxlint` on the changed files: clean. `tsc --noEmit`: no errors in the
changed files (the remaining errors are the existing `astro:content`
implicit-any ones, same as `main`). `prettier -c` reports only the
existing long lines in `openapi-markdown.ts`.
- No build was run, per `CLAUDE.md`.

## First-screen impact

Only `<head>` text changes: longer title/description and 4 more `<link
rel="alternate">` tags on API pages (about 0.35 KB of HTML). No new
requests, no script or data changes; docs pages are unchanged.

## Post-deploy check

Request each pair and compare `<title>`, `meta description`, hreflang:

| Docs page | API page |
|---|---|
| `/docs/account/dca/update-dca` | `/docs/api/dca_update` |
| `/docs/account/dca/calc-date` | `/docs/api/dca_calc_date` |
| `/docs/market/top-movers` | `/docs/api/top_movers` |
| `/docs/content/topics/topic-detail` | `/docs/api/topic_detail` |
| `/docs/quote/pull/intraday` | `/docs/api/ws-intraday` |
| `/zh-HK/docs/market/top-movers` | `/zh-HK/docs/api/top_movers` |

Expected: title and description differ within each pair; API page title
contains `(METHOD /path)` or `(WebSocket cmd N)`; API page has
`hreflang` `en`, `zh-Hans`, `zh-Hant`, `x-default` pointing to
`/docs/api/<id>`, `/zh-CN/docs/api/<id>`, `/zh-HK/docs/api/<id>`.

Sample: `curl -s https://open.longbridge.com/docs/api/top_movers | grep
-o '<title>[^<]*'` → `<title>Top Movers (POST
/v1/quote/market/stock-events) · API Reference`.

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-authored-by: chiba <zhiqiang.ni@longbridge-inc.com>
Co-authored-by: Claude Opus 5.5 <noreply@anthropic.com>
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant