apache / apache/rocketmq-dashboard

[Studio][Docs] Align Message and Producer API documentation with current controllers

Closed
#4,151 1 comment 0 reactions 0 assignees View on GitHub
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

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.