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: | Issue type | How to detect | |------------|--------------| | Wrong URI prefix | Path in doc doesn't match any constant in path.rs | | Non-existent route | Path in doc has no corresponding constant in path.rs | | Extra request field | Field in doc not present in the handler's request struct | | Missing request field | Required field in handler struct missing from doc | | Wrong response field | Field in doc not in response struct | | Missing response field | Key response field not documented | | Wrong HTTP method | GET vs POST mismatch | | Wrong field type | e.g. doc says `string` but struct says `u64` | ### 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 ```