Fix two project group listing response entity annotations
What does this MR do and why?
Two desc blocks in lib/api/projects.rb name Entities::Group as the response, and both endpoints call present_groups, the helper defined a few hundred lines above them in the same file, which presents with: Entities::PublicGroupDetails.
| Endpoint | Annotated | Actually presented |
|---|---|---|
GET /projects/:id/share_locations |
Group |
PublicGroupDetails |
GET /projects/:id/invited_groups |
Group |
PublicGroupDetails |
Their sibling GET /projects/:id/groups calls that same helper and is annotated Entities::PublicGroupDetails, correctly. So three adjacent routes share one helper and two of them disagree with it about what it returns.
PublicGroupDetails is BasicGroupDetails plus avatar_url, full_name and full_path, which is six keys, against roughly seventy for Group. The generated OpenAPI document therefore describes these two responses as an object an order of magnitude larger than the one they send.
Only the annotations change. No runtime behaviour does: a desc block is documentation metadata, and what an endpoint sends is decided by its present call.
How I confirmed it, against the API rather than by reading
Both endpoints answer with exactly six keys on GitLab.com, and they are the PublicGroupDetails six:
GET /projects/:id/share_locations -> id, name, avatar_url, web_url, full_name, full_path
GET /projects/:id/invited_groups -> id, name, avatar_url, web_url, full_name, full_pathAbout the generated document
doc/api/openapi/openapi_v3.yaml says not to edit it directly, and I did not write its content by hand.
The change is bin/rake gitlab:openapi:v3:generate output, produced in an environment whose baseline generation reproduced the committed document byte for byte before the change, and then applied to current master rather than committing a document generated against an older revision, since the file moves daily.
The diff is two $ref lines and nothing else. It adds no schema, because APIEntitiesPublicGroupDetails is already a component of the document: GET /projects/:id/groups references it. gitlab:openapi:v3:check_docs is the authority and will confirm it in this pipeline.
References
Same class as !254698 (merged), which I opened today for three annotations in lib/api/project_job_token_scope.rb. That one is a different file and a different feature category, so I have kept them apart rather than growing its scope; a reviewer who wants them together is welcome to say so.
I found both while building a 1:1 comparison between the REST API and a GitLab client, where the route annotation is read as the response contract. This pair was the single largest discrepancy in that comparison: 49 fields reported as missing from a type that already publishes everything these endpoints send.
Screenshots or screen recordings
Not applicable: no user interface change.
How to set up and validate locally
bin/rake gitlab:openapi:v3:check_docspasses on this branch.- Read the two
descblocks against thepresent_groupscall in each endpoint body, and against the helper's ownwith:option in the same file. - Against any instance, call either endpoint and count the keys: six, not seventy.
MR acceptance checklist
This MR is a documentation-metadata correction with no runtime, database, performance or security impact. No changelog entry: per the changelog guidelines an MR whose only effect is on documentation does not take one, and the API's behaviour is unchanged.
I am an outside contributor and cannot set labels on this project, so triage and the reviewer roulette are left to do that.