apache / apache/rocketmq-dashboard
[Studio][Docs] Align Message and Producer API documentation with current controllers
- Dominant language
- Java
- Stars
- 1.4k
- Forks
- 683
- Avg merge
- 2d 12h
- Merged PRs (30d)
- 62
Description
## Problem
`docs/api-spec.md` no longer matches the current Message and Producer controller surfaces. The quick-reference table lists only the legacy message query and message-id trace routes, while the code also exposes paged queries, trace-by-key, queue browsing, direct consumption, and two Producer connection endpoints.
The detailed Message section also omits required `instanceId`, the optional `tag` and `traceTopic` filters, and describes millisecond timestamps as ISO strings even though the controller and VOs use integer epoch milliseconds. There is no detailed Producer endpoint section.
## Expected documentation
Synchronize the documentation with `MessageController`, `ProducerController`, their response VOs, and the frontend API clients:
- add the five missing Message routes to the quick reference and detailed section;
- document `traceTopic` for message-id and business-key trace lookup;
- document paged message query metadata and truncation semantics;
- document queue offset lookup and exact-offset message reads;
- document direct-consume request and response fields;
- document Producer group suggestions and connection inventory/summary responses;
- correct Message timestamp parameter and response types to Unix milliseconds;
- keep quick-reference numbering contiguous.
## Scope
This is a documentation-only change for `MessageController` and `ProducerController`. It does not change runtime APIs or attempt a repository-wide API documentation rewrite.
## Verification
Cross-check every documented method, path, parameter, default, limit, and response field against the current controller, service DTO/VO, and frontend API client.
Contributor guide
No contributing guide indexed for this repository
Research direction
Start with docs/api-spec.md, then compare each MessageController and ProducerController method with their response VOs, service DTOs, and frontend API clients. Verify routes, parameters, defaults, limits, pagination and response fields, including Unix-millisecond timestamps; done means the five Message routes, Producer section, and contiguous quick-reference numbering are complete and accurate.
Written by the indexing model from the issue text.
Assessment
- Tech stack
- java
- Domain
- api, documentation
- Issue type
- Documentation
- Difficulty
- 4/5
- Estimated time
- 3-5 days
- Activity status
- Active
- Clarity
- Clearly specified
- Newbie friendliness
- 68/100