openapi 模板

Do not modify AGENTS.md; it is managed by nitrogen and only `nitrogen update` regenerates it
With the user's explicit consent, you may modify the files referenced by AGENTS.md (`glossary.md`)
Do not describe features to be implemented in future versions, or add next-version TODO-style statements; stay limited to the present, always assume the current version is the final iteration.

## Product Documentation Positioning

The open-platform developer guide targets external and third-party developers integrating with the platform. Its goal is to take a developer from zero to a working integration: register an application, obtain credentials, authenticate, call public APIs, receive webhooks, and handle rate limits and error codes. Readers have no access to internal knowledge: document only externally-exposed capabilities and their observable behavior, never internal implementation. Internal API references live in `docs/api_references`; do not copy them here — this site documents the public subset with external-facing semantics.

## doc-doc Usage Guidelines

- **`docdoc.json` configures the site**: `languages` maps language codes to display names (`{lang_code: name}`) and the first declared language is the default; `title` is an i18n map `{lang_code: site title}` resolved per page language (missing languages fall back to the first language, then `"文档"`); `copyright` sets the footer text (i18n map `{lang_code: text}`, falling back to the first language); `icon` accepts an emoji/short text, a remote URL, or a relative path to an image inside the docs root (local files are inlined as base64 at render time); when unset, the header falls back to a default document icon. Without a `docs` array, each `<lang>/` directory is one whole document and pages live at `<lang>/...`; the site root redirects to the first page
- **`docs` declares sub-documents, rendered as a horizontal tab bar under the top header**: each entry declares only `name` (URL segment, unique, snake_case) and `path` (source directory under the site root); the document's own manifest `<path>/doc.docdoc.json` carries `title` (i18n map `{lang_code: tab label}`), `languages` (must list every language the document ships), and an optional `renderer` — `tree` renders a collapsible outline sidebar, `submenu` renders a drill-down sidebar; defaults to `tree`. With `docs` declared, content roots live at `<path>/<lang>/` and URLs become `<lang>/<name>/...`. Format: `{"name": "my-platform", "title": {"cn": "My Platform"}, "languages": {"cn": "简体中文"}, "docs": [{"name": "openapi", "path": "openapi"}]}`, with `openapi/doc.docdoc.json` = `{"title": {"cn": "OpenAPI"}, "languages": {"cn": "简体中文"}}`
- **Headings may declare an icon with `<Icon name="..." />`** using Phosphor bold icon names: wherever it appears inside the heading text, the icon always renders at the very front of the heading; build-time title cleanup strips it from sidebar entries, the search index, and the heading slug
- **Code fence signature is ``` ```language:type#tab ``` **: `language` selects syntax highlighting; `:type` hands the fence to the interface renderer (e.g. `jsonschema:parameters`, keeping its Table ⇄ TypeScript dual-view); `#Tab Label` merges the block into a tab group — adjacent fenced blocks (blank lines only between them) that EACH carry a `#Label` merge into one tabbed code block; a lone labeled block or a run interrupted by any other content stays a plain code block, and `d2` diagram fences never merge into tabs
- **Directory and file names must be English and match one-to-one across languages**: directories and `.md` file names under `cn/` and `en/` must be identical, only the content differs by language, ensuring exact page correspondence when switching languages
- **Directory and file names use kebab-case English slugs**: lowercase letters and hyphens (e.g., `getting-started/`, `token-refresh.md`), no spaces, underscores, or Chinese characters
- **Every directory must have an `index.md`**: content should only be a short overview plus a TOC macro; do not hand-write a list of sub-pages
- **Choose the TOC macro by chapter type**: use `` to show only direct sub-pages; do not recursively list overly deep levels
- **Use `metadata.docdoc.json` to control sidebar order and renderer (optional)**: directories that need neither can omit this file; doc-doc will sort alphabetically and inherit the sidebar renderer. The file is an **object** with optional keys: `order` (sibling entry order, e.g. `{"order": ["a.md", "b.md"]}`) and `renderer` (`"tree" | "submenu" | "group"`, which overrides the sidebar renderer for this directory's subtree — the deepest configured directory wins per page, falling back to the sub-doc's `renderer` in doc.docdoc.json). Directory names have no extension; file names include the `.md` extension. **Do not list `index.md`** — clicking the directory name in the sidebar navigates to it, so it does not need a separate entry
- **Directories containing only `index.md` are prohibited; use a single file when there are no sub-files, use a directory only when there are**:
  - A topic with no sub-files must use a top-level `.md` file directly (e.g., `changelog.md`); creating an empty wrapper such as `changelog/index.md` is forbidden
  - Only make a directory (with an `index.md` overview page inside) when the topic genuinely needs to be split into multiple sub-files
  - This does not conflict with the "every directory must have an `index.md`" rule - the latter constrains directories only and does not require every topic to become a directory
  - Placeholder chapters (content only "To be added") follow the same rule: use a top-level `.md` file as the placeholder, or do not create the chapter until there are actual sub-pages
  - The following two cases must use a single file instead of a directory:
    1. Only `index.md` exists with no other sub-files
    2. `index.md` and one other file exist, but `index.md` merely links to that file without real body value
  - Criterion: a directory must contain at least one `.md` file or subdirectory besides `index.md`, and `index.md` itself must have independent body value; otherwise using a directory is forbidden
- **Prefer splitting files over creating large single files**: when a `.md` file's content can clearly be divided by sub-topic, prefer splitting it into multiple smaller `.md` files (and promote to a directory when necessary) rather than letting a single file grow too long, which harms readability, maintenance, and navigation. Split granularity target: each file focuses on a single sub-topic
- **Avoid naming conflicts**: at the same level, a directory name and a `.md` file name cannot be identical (e.g., you cannot have both a `webhooks/` directory and a `webhooks.md` file)
- **Use relative paths for links between files**: `[example link](../example/example-1.md)`; doc-doc will convert them to SPA routes automatically
- **Prefer D2 for diagrams**: flowcharts, architecture diagrams, and relationship diagrams should use ` ```d2 ` code blocks (doc-doc renders D2 via the bundled `@terrastruct/d2` WASM package — no external `d2` binary required). Mermaid is still supported; use it only when D2 cannot satisfy the requirement
- **A glossary `glossary.md` is required**: place `glossary.md` at the document root (next to `docdoc.json` and language directories such as `cn/`, `en/`) to collect platform terms, abbreviations, key concepts, and definitions. This file is not intended for end users to browse directly; it is a terminology/translation consistency reference for AI and authors. The glossary must use a table format and include at least the following columns:
  - `English` (required): the original/standard English term
  - `中文` (required): the corresponding Simplified Chinese translation
  - `...`: append other languages actually used in the documentation in order, such as `日本語`, `Français`, etc.

  Example:

  | English       | 中文         | 日本語           |
  | ------------- | ------------ | ---------------- |
  | Access Token  | 访问令牌     | アクセストークン |
  | Webhook       | 回调通知     | ウェブフック     |
- **Keep glossary term mappings up to date**: the same proper noun must map one-to-one across language versions; update it when terms are added, changed, or deprecated
- **Glossaries must stay in sync across languages**: all language versions must keep glossary entries, meanings, and mappings consistent to avoid inconsistency across the multi-language site

## Rules

- **Document only public, externally-exposed capabilities**: anything not officially open to third-party developers is forbidden here; internal endpoints and implementation details belong to `docs/api_references`
- **One integration topic per `.md` file**: app registration, token issuance, token refresh, signature calculation, etc. each get their own file; do not mix topics in one file
- **One public API endpoint per `.md` file**: each public endpoint gets its own file, organized under `apis/<resource>/`; different endpoints must be kept in separate files
- **Endpoint documents follow the fixed single-endpoint structure**: title `# #ACTION# Uri - Description`, then `## Overview` (URL / Action table), `## Authorization`, `## URL Path Parameter`, `## URL Search Parameters`, `## Request Body`, `## Response Body`, `## Response Code Reference`. Sections with no corresponding content are omitted entirely; do not keep empty headings or write "None"
- **Shared platform conventions are centralized, not repeated**: `authentication.md` (credential types, token lifecycle, signing), `rate-limits.md` (quota tiers, throttle behavior, 429 handling), and `error-codes.md` (the shared error code table) live directly under the project root; individual endpoint documents list only the codes unique to them and do not repeat the shared table
- **Webhooks are documented as their own chapter**: one file per event category, describing trigger conditions, payload structure, and retry policy; signature verification of webhook deliveries is documented once in its own file
- **SDK usage is documented per language**: each officially supported language gets its own installation + quickstart file; do not merge multiple languages into one file
- **Versioning and deprecation are documented as facts**: the changelog records released changes only; a deprecated endpoint states its removal date and its replacement
- **Every endpoint document includes a complete runnable example**: a copy-pasteable request example (cURL or the official SDK) with realistic values, matching the documented auth scheme
- **Direct references to related files are forbidden**: do not list links pointing to related files in forms such as "Related docs: XXX"; files may be moved or renamed, causing links to become invalid. When directing readers to related content, use the `?keyword` format to trigger doc-doc's site search, which locates targets by keyword and is more robust than hardcoding file paths
- **Edit results must not include explanatory notes**: when performing edits such as deletions, merges, or replacements, output the final result directly; do not append any explanatory notes (e.g., "Removed XX", "No separate XX chapter", "This was originally XX", etc.)
- **Do not use speculative wording such as "suggest" or "in the future"**: documentation outputs definitive content; phrases such as "suggest in the future...", "later you can...", "may in the future..." that describe changes not confirmed to happen or unverified proposals are forbidden. Describe only currently established facts and currently effective practices
- **No need to restart the docdoc service after editing docs**: restarting the service is not this AGENT's task; verify documentation by checking the `.md` files themselves for content and structure

## Documentation Directory Division

> The following directory structure demonstrates the progression order; actual content should be based on platform functionality. Chapter numbers and hierarchy must be followed strictly, but sub-item names, counts, and specific business details can be adjusted per project.

The open-platform guide targets external developers who need to ship an integration; the directory should follow the progression "understand the platform first, then get access, then integrate by capability, then operate".

1. Introduction
   - Example content 1
   - Example content 2

2. Getting Started
   - Example content 1
   - Example content 2

3. Authentication
   - Example content 1
   - Example content 2

4. APIs
   - Example content 1
   - Example content 2

5. Webhooks
   - Example content 1
   - Example content 2

6. SDKs
   - Example content 1
   - Example content 2

7. Rate Limits
   - Example content 1
   - Example content 2

8. Error Codes
   - Example content 1
   - Example content 2

9. FAQ
   - Example content 1
   - Example content 2

10. Changelog
    - Example content 1
    - Example content 2

**Ordering recommendation**: overall follow `introduction → getting-started → authentication → apis → webhooks → sdks → rate-limits → error-codes → faq → changelog`. Put `changelog` last so developers integrate against the current version before consulting release history.

## Directory Structure Example

```
document/
  docdoc.json
  glossary.md                 # Glossary at the same level as language dirs, collecting terms, abbreviations, and key concepts
  cn/
    index.md
    metadata.docdoc.json  # {"order": ["introduction", "getting-started", "authentication", "apis", "webhooks", "sdks", "rate-limits.md", "error-codes.md", "faq.md", "changelog.md"]}
    introduction/
        index.md
        example-1.md
        example-2.md
    getting-started/
        index.md
        example-1.md
        example-2.md
    authentication/
        index.md
        app-registration.md
        token-issuance.md
        token-refresh.md
        signature.md
    apis/
        index.md
        user/
            index.md
            get-by-id.md
        order/
            index.md
            create.md
    webhooks/
        index.md
        event-order-created.md
        signature-verification.md
    sdks/
        index.md
        nodejs.md
        python.md
    rate-limits.md
    error-codes.md
    faq.md
    changelog.md
  en/
    ...                         # Directory and file names identical to cn/
```

## Glossary

@glossary.md

| English | 中文 |
| ------- | ---- |