docs: regenerate the Platform API reference for the items + pageInfo list shape

Open Beginner friendly
#11,583 0 comments 0 reactions 0 assignees View on GitHub

Nobody has claimed this yet.

Assessment

Difficulty
2/5
Estimated time
1-3 hours
Newbie friendliness
78/100
Issue type
Documentation
Clarity
Clearly specified
Activity status
Active
Tech stack
openapi
Domain
documentation

Research direction

In docs-mintlify, start with api-reference/api.yaml and run SRC_SPEC=/path/to/cubejs-enterprise/packages/console-server/open-api-spec-public-v3.1.yaml yarn api:extract. Check the resulting docs.json and introduction.mdx, then run yarn api:check. Done means list responses use items and pageInfo, list endpoints expose first and after, and DeploymentVersionsResponse no longer documents data.

Written by the indexing model from the issue text.

Description

docs-mintlify/api-reference/api.yaml is stale against the current Console Server public OpenAPI spec.

The API standardized list responses on items + pageInfo, keeping data/count/pagination only as deprecated aliases, and gave every list endpoint first/after. The committed reference predates that:

  • DeploymentVersionsResponse is still documented as { data } — a field that no longer exists on that endpoint (it was reworked to items + pageInfo only, a deliberate break on an unreleased response).
  • ~30 list endpoints are missing items, pageInfo, and the first/after query params.

Nothing in this repo's CI checks the reference for drift, so it went unnoticed. Regenerating touches api.yaml, docs.json, and introduction.mdx, which is why it was kept out of the Rust-only fix in #11582:

cd docs-mintlify && SRC_SPEC=/path/to/cubejs-enterprise/packages/console-server/open-api-spec-public-v3.1.yaml yarn api:extract

The spec is generated in cubejs-enterprise/packages/console-server via yarn generate:open-api:spec-public. yarn api:check verifies the committed artifacts without writing — worth wiring into CI here so this can't go stale again.

Context: #11582.

Dominant language
Rust
Stars
20.9k
Forks
2.1k
Avg merge
1d 31m
Merged PRs (30d)
203

Contributor guide

Open the contributing guide

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. Open a pull request that references the issue number.

More from cube-js/cube

All issues in cube-js/cube

Similar issues

More Rust issues

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.