unbridled-41 opened a new pull request, #5438:
URL: https://github.com/apache/rocketmq-dashboard/pull/5438
## Problem / Evidence
The topic/group write sections of `docs/api-spec.md` still describe the
pre-instance-scoped contract, so a request built exactly as documented is
rejected with 400:
| Section | Spec said | Code requires |
|---|---|---|
| §5.5 delete Topic | `name` only | `DeleteTopicDTO.instanceId`
`@NotBlank(message = "instanceId is required")` |
| §5.8 send to Topic | no `instanceId` | `MetadataService.sendMessage` →
`requireWriteInstance(..., required=true)`, `400 instanceId is required` |
| §6.6 delete Group | `name` only | `DeleteConsumerGroupDTO.instanceId`
`@NotBlank(...)` |
| §6.7 reset offset | `timestamp` as an ISO 8601 **string**, `topic`
**optional** ("不传则全部重置") | `ResetConsumerOffsetDTO`: `@NotBlank instanceId`,
`@NotBlank name`, `@NotBlank topic`, `@NotNull @Positive Long timestamp`;
`MetadataService.resetOffset` calls `requireName(topic, "topic name")` and no
reset-all branch exists on this endpoint |
| §6.8 import groups | `multipart/form-data` with a `file` field, response
`{imported, failed, errors}` | `ConsumerGroupController:104-108` takes `@Valid
@RequestBody ImportConsumerGroupsDTO` (`instanceId`, `groups`);
`ImportConsumerGroupsResultVO` returns `imported`, `failed`, `groups`,
`failures[{index,name,message}]`. `grep -rn "MultipartFile"
server/src/main/java` is empty |
`POST /api/groups/reset-offset
{"name":"cg","timestamp":"2026-10-03T00:00:00Z"}` therefore fails to parse, and
`{"name":"cg","timestamp":1780000000000}` fails with `topic is required` —
while the MCP tool catalog already documents the real contract
(`tool-catalog/tools/group.yaml:442,458`: `topicName` required, epoch
milliseconds).
## Root cause / Fix
Sections 5–7 were written from the front-end mock data and were never
realigned when resource ownership made `instanceId` mandatory on writes and the
group import moved to a JSON DTO. Align the five request/response tables with
the DTOs, and note the import cap (`@Size(max = 100)`).
## Priority & scoring
PRIORITY 77 = 影响 24 (every documented write request in these sections fails
validation) + 波及 16 (the whole API-spec audience for topics and groups) + 可复现
20 (deterministic validation errors) + 维护价值 17 (the spec regains parity with
the DTOs and with `tool-catalog`).
FIX_CONFIDENCE 90: the corrections are read directly off the DTO annotations
and the controller signatures; no code changes.
## Tests
Documentation-only change; each row verified against the code:
- `DeleteTopicDTO.java:33-34`, `DeleteConsumerGroupDTO.java:33-34` —
`instanceId` `@NotBlank`.
- `SendMessageDTO.java:32` + `MetadataService.java:293-298` —
`requireWriteInstance(..., true)`.
- `ResetConsumerOffsetDTO.java:27-43` — all four fields required,
`timestamp` a `Long`.
- `ImportConsumerGroupsDTO.java:30-36` and
`ImportConsumerGroupsResultVO.java:30-52` — JSON body shape and result fields.
## 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]
