unbridled-41 opened a new pull request, #5435:
URL: https://github.com/apache/rocketmq-dashboard/pull/5435
## Problem / Evidence
`docs/api-spec.md` §4.5-4.9 document five NameServer operations with success
responses (`NameServerInfo`, `{ success: boolean }`), but every one of them
always ends in `501`:
- `cluster/broker/ClusterService.java:581-624` — `createNameServer`,
`updateNameServer`, `restartNameServer`, `upgradeNameServer`,
`deleteNameServer` each validate the command/cluster/address and then `throw
unsupportedOperation(...)`, mapped to `501` by `GlobalExceptionHandler`.
- `POST /api/nameservers/restart {"clusterId":"c","addr":"10.0.0.1:9876"}`
therefore returns `501`, never the documented `{ success: true }`.
The spec already handles the identical situation for the Proxy restart —
§4.11 carries a paragraph plus a `501` row (`docs/api-spec.md:655,663`) — but
§4.5-4.9 were missed, and the NameServer endpoints that *are* implemented (`GET
/api/nameservers`, `POST /api/nameservers/registry/{create,update,delete}`,
`cluster/nameserver/NameServerController.java:43-67`) appear nowhere in the
document.
## Root cause / Fix
The mock-era §4 sections were never realigned after the registry endpoints
landed. Add the §4.11-style warning to each of the five sections, and point
readers at the implemented registry endpoints instead of leaving them
undocumented:
> **未实现**：与 4.11 的重启 Proxy 相同，本接口在完成集群与地址校验后固定抛出
`501`，因此下表中的成功响应不会出现。NameServer 注册表的查询与增删改由 `GET /api/nameservers` 与 `POST
/api/nameservers/registry/{create,update,delete}` 提供，本 spec 尚未收录。
## Priority & scoring
PRIORITY 78 = 影响 24 (five documented operations that can never succeed; the
working alternative is undiscoverable from the spec) + 波及 16 (every API
consumer following the spec) + 可复现 20 (deterministic: the methods always throw)
+ 维护价值 18 (matches the treatment §4.11 already received).
FIX_CONFIDENCE 85: the warning mirrors the existing §4.11 wording and names
the real endpoints; adding full schemas for the registry endpoints is left out
of scope.
## Tests
Documentation-only change; every claim verified against the code:
- `ClusterService.java:581-624` — all five methods end in
`unsupportedOperation(...)`.
- `GlobalExceptionHandler` maps it to `501`.
- `NameServerController.java:43-67` — the implemented `GET /api/nameservers`
and `/registry/*` endpoints; `grep -c registry docs/api-spec.md` was 0 before
this change.
- No Markdown structure is altered: the notes are inserted between the
endpoint fence and the `**Request Body:**` table of each section.
## Risk
None. Documentation only; no code, schema or asset changes.
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: [email protected]
For queries about this service, please contact Infrastructure at:
[email protected]
