Update API Docs

update-api-docs

Perform a full audit of the admin-server HTTP API documentation against the actual source code, then fix all discrepancies and sync both Chinese and English versions.

Usage

/update-api-docs
/update-api-docs <doc_file>

Examples

/update-api-docs
/update-api-docs docs/zh/Api/MQTT.md
/update-api-docs docs/zh/Api/CLUSTER.md

When no file is specified, audit all doc files under docs/zh/Api/ and docs/en/Api/.

Source of Truth

• Route paths: src/admin-server/src/path.rs — all path constants are defined here
• Handler structs: src/admin-server/src/ subdirectories — request/response types per feature area
• Route nesting: src/admin-server/src/server.rs — all routes under GET/POST /api/... are nested via .nest("/api", self.api_route()); health and debug routes are mounted outside /api

Key path facts to remember:

• Health routes have no /api prefix: /health/ready, /health/node, /health/cluster
• Debug routes have no /api prefix: /debug/pprof/flamegraph, /metrics
• Cluster index is GET / (no /api prefix)
• Tenant routes: /api/cluster/tenant/* (NOT /api/tenant/*)
• User routes: /api/cluster/user/* (NOT /api/mqtt/user/*)
• Message routes: /api/cluster/message/* (NOT /api/mqtt/message/*)
• Connector routes: /api/cluster/connector/* (NOT /api/mqtt/connector/*)
• MQ9 routes: /api/mq9/mail/list, /api/mq9/agent/list

Execution Flow

Step 1 — Read path.rs

Read src/admin-server/src/path.rs in full. This file contains all route path constants. Extract every path constant into a checklist — these are the only valid routes.

Step 2 — Read server.rs

Read src/admin-server/src/server.rs to understand which paths get the /api prefix and which do not. Note which routers are nested under .nest("/api", ...).

Step 3 — Read handler files

For each handler subdirectory (cluster/, mqtt/, nats/, mcp/, etc.), read the relevant handler files to extract:

• Exact request struct field names and types
• Exact response struct field names and types
• Any validation constraints (e.g. length(1..=256))

Focus on the structs decorated with #[derive(Deserialize)] (request) and #[derive(Serialize)] (response).

Step 4 — Read doc files

For each doc file to audit:

1. Extract every documented endpoint: method + path
2. Extract every documented request field
3. Extract every documented response field

Step 5 — Compare and identify discrepancies

Check each documented endpoint against the source of truth:

Step 6 — Fix all discrepancies

Fix all identified issues in the Chinese doc files first:

• Wrong URI prefix: Replace with the correct path from path.rs
• Non-existent route: Replace with the actual route, or add a clear note if the route was removed
• Extra request field (e.g. retain in SendMessageReq): Remove from doc
• Missing required field: Add to the parameter table and example JSON
• Wrong field type: Correct to match the struct definition
• Curl examples: Update all example URLs to match fixed paths, update example bodies to match fixed field lists

After fixing the Chinese docs, sync the English docs to match:

• All endpoint paths must be identical to the Chinese version
• All field names and types must be identical
• Descriptions should be the English equivalent

Step 7 — Verify

After editing, grep the fixed doc files to confirm:

• No old wrong paths remain
• No removed fields remain in request examples
• All curl examples use the correct paths

What NOT to change

• Do not alter correct endpoints
• Do not change prose descriptions unless they are factually wrong
• Do not reformat sections that don't contain errors
• Do not change connector type reference tables or enum value tables (these are application-level, not route-level)
• Do not modify zh/en sidebar files unless a new doc file was created

New doc files

If a route area exists in path.rs but has no corresponding doc file (e.g. a new protocol like mq9):

1. Create docs/zh/Api/<Name>.md with all routes documented
2. Create docs/en/Api/<Name>.md as the English version
3. Add both to the appropriate sidebars in docs/.vitepress/src/sidebars/zh.mts and en.mts

Output Format

After completing the audit, report:

## API Doc Audit Results

### Files checked
- docs/zh/Api/CLUSTER.md
- docs/zh/Api/MQTT.md
- docs/zh/Api/Connector.md
- docs/en/Api/CLUSTER.md
- docs/en/Api/MQTT.md
- docs/en/Api/Connector.md

### Discrepancies found and fixed

| File | Section | Issue | Fix |
|------|---------|-------|-----|
| zh/MQTT.md | §6.1 | Wrong path: /api/mqtt/user/list | → /api/cluster/user/list |
| zh/MQTT.md | §11.1 | Extra field: retain | Removed |
| zh/CLUSTER.md | §8 | Non-existent: GET /cluster/healthy | → GET /health/node |
| ... | | | |

### New files created
- docs/zh/Api/MQ9.md
- docs/en/Api/MQ9.md

### No issues found in
- docs/zh/Api/COMMON.md