OpenAPI: array responses and fields are typed as single objects in openapi_v3.yaml

Everyone can contribute. Help move this issue forward while earning points, leveling up and collecting rewards.

Summary

The REST API returns arrays for list endpoints and for plural entity fields, but doc/api/openapi/openapi_v3.yaml types them as a single object, so strict typed clients fail to decode real responses. The API is correct — this is a spec-accuracy defect; no behaviour change is needed to fix it.

Where it shows up

  • List endpoints — e.g. GET /projects/:id/merge_requests/:iid/notes is typed as APIEntitiesNote, not [APIEntitiesNote].
  • Nested fields — on APIEntitiesMergeRequest, assignees and reviewers are typed APIEntitiesUserBasic (one user) but the API returns an array. (labels is typed correctly, so it's field-by-field, not uniform.)

Evidence

A strict client decoding a real response throws typeMismatch … found an array instead, confirmed live: GET /projects/278964/merge_requests/1 returns 200 with a valid body; only the typed decode disagrees.

Suggested fix

Mark the array exposures/responses (is_array: true on success declarations, documentation: { is_array: true } on plural exposures) and ensure the v3 generator (gitlab-grape-openapi) honours them. Documentation-only change.

Related

  • #506161 (closed) — the same defect in the deprecated openapi_v2.yaml, fixed narrowly for merge request list endpoints in !214714 (merged); openapi_v3.yaml has the same under-typing today.
  • #592838 and #604896 — scalar counterparts of the same spec-accuracy problem: boolean exposures defaulting to string in #592838, numeric fields (e.g. APIEntitiesMilestone.group_id) in #604896.
  • #519959, #591007 (closed) — context: OpenAPI v3 tooling and spec validation. Note these mistyped schemas are valid OpenAPI, so validation alone won't catch them.
Edited by laconicman