docs: regenerate the Platform API reference for the items + pageInfo list shape
- 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
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