cube-js / cube-js/cube

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
Dominant language
Rust
Stars
20.8k
Forks
2.1k
Avg merge
1d 2h
Merged PRs (30d)
181

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:

```bash
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.

Contributor guide

Open the contributing guide

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.

Assessment

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

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.