broker-api: move required permission into its own field - #68
Open
hogan-yuan wants to merge 7 commits into
Open
Conversation
…uthorization row The permission-key / LB-only badges were rendered inline on the Authorization header field, implying they were part of the token header. Split them into a separate 'Permission' field (styled like Authorization) within the same section, with its own description. Add localized Permission title + description strings.
Promote the Permission field to a standalone <section> with its own heading, rather than a second row inside the Authorization section.
Deploying whale-docs with
|
| Latest commit: |
f8fa1a2
|
| Status: | ✅ Deploy successful! |
| Preview URL: | https://6acdd14d.whale-docs.pages.dev |
| Branch Preview URL: | https://broker-api-permission-field.whale-docs.pages.dev |
- #4 Endpoint/examples no longer hardcode the Test host: derive from servers — Production (b-api.lbkrs.com) for normal ops, Test for /v1/datasets/* (prod 404s), with an environment note per op. - #5 Add the standard 400/401/403/408 responses to the 136 ops (per locale) that declared only 200 (dataset queries + risk-control writes), matching siblings. - #7 Strip 226 internal meta-commentary notes (未实调 / 字段以真实接口为准) from public descriptions. - #8 Fix the 4 generator-leak domains' info.title (Whale OpenAPI 自动生成 → Longport Whale Broker API) and English server descriptions. - #12 Collapse 907 redundant English 'Specifies X' echoes.
…bility) - llms.txt: crawlable index of all Broker + Trading operations (English) with links; notes the .md-per-page convention and the response envelope. - robots.txt: allow-all + sitemap pointer (was missing).
…s (audit #6/#13) - #6 Translate the 140 operations (risk-control 57, clearing 39, ipo 20, fund 14, service-param 6, reports 2, virtual-assets 2) whose English summary/description had fallen back to Chinese. 0 CJK left in en op summary/description. - #13 Add machine-readable x-format (unix-millisecond/second-timestamp, date-int-yyyymmdd) to 43 numeric time fields that state their unit. - #9 Investigated: the 25 'required-asserting' fields are all CONDITIONALLY required (order-type / market / reward-type dependent) or explicitly 'not a required field' — forcing them into required[] would be wrong, so no change.
…es (audit #6/#11/#14) - #6 Translate the remaining 32 unique Chinese field-level descriptions (83 occurrences) + 4 error-envelope component descriptions. 0 CJK left anywhere in en summary/description. - #11 Build x-enum-details {value,label} for 1258 enum fields whose option meanings were only in prose; de-duplicate the prose option list from 1410 fields that already had x-enum-details. Per-locale labels from each file's own prose. - #14 Add a valid example (first enum value) to 3573 request-side enum fields. (Real data-sample values were deliberately NOT used — they contain un-sanitized account numbers/PII.)
Replace synthetic enum examples on dataset query FILTER fields with the real value the live API returned (from cached data/dataset/<template_id> samples) — 1707 fields, e.g. market='OSL', direction='Sell', state='Settlement Completed'. Safety: only request-side filter fields (query codes/enums), NOT response rows (which carry un-sanitized free text). PII-identifying field names are skipped — account_id / bank_account / member / customer / phone / email / card / id_card etc. — so no real account, bank, or contact identifiers are published.
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
What
On broker-api operation pages, the required permission (
x-permission-key) and the LB-only badge were rendered inline on theAuthorizationheader field, which reads as if the permission were part of theAuthorization: Bearertoken header.This splits the permission out into its own
Permissionfield, styled like the Authorization field (parallel divided row in the same section), with its own description:Authorizationrow:string/header/Required+ the token instruction.Permissionrow: the permission-key badge(s) + LB-only badge + a short description (or the 'no dedicated permission key' note).Adds localized
title/requiredDescstrings (en / zh-CN / zh-HK) topermissionLabels. The markdown (.md) endpoint already rendered permissions as a separate## Permissionssection, so no change there.Verify
astro buildpasses (3587 pages, 0 errors). Rendered pages confirmed: Authorization row no longer carries permission badges; Permission is its own row; the no-key and LB-only cases render correctly.