Fix three job token scope response entity annotations
What does this MR do and why?
Three desc blocks in lib/api/project_job_token_scope.rb name a response entity the endpoint does not present, so the generated OpenAPI document describes the wrong response shape for three job token scope endpoints.
| Endpoint | Annotated | Actually presented |
|---|---|---|
GET /projects/:id/job_token_scope/groups_allowlist |
BasicProjectDetails |
BasicGroupDetails |
POST /projects/:id/job_token_scope/allowlist |
BasicProjectDetails |
ProjectScopeLink |
POST /projects/:id/job_token_scope/groups_allowlist |
BasicGroupDetails |
GroupScopeLink |
Each wrong line was introduced in the same commit as the present call it contradicts, so this reads as a copy-paste at introduction rather than drift.
doc/api/project_job_token_scopes.md already documents all three correctly, so the page and the annotations disagreed and the page was right. Only the annotations change here, and no runtime behaviour does: success status:, model: is Grape documentation metadata, and what an endpoint sends is decided by its present call.
The list endpoint's own BasicProjectDetails annotation is correct and is deliberately left alone.
How I confirmed it, against the API rather than by reading
I checked the three responses on GitLab.com rather than inferring them from the source:
GET .../groups_allowlistreturnsid,web_urlandname, which isBasicGroupDetails. The sibling projects allowlist, which really is annotatedBasicProjectDetails, returns seventeen keys.- Both creations return a two-key link object carrying no
idat all:source_project_idwithtarget_project_id, andsource_project_idwithtarget_group_id.
About 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 four hunks are bin/rake gitlab:openapi:v3:generate output. I produced them in a local environment whose baseline generation reproduced the committed document byte for byte before the change, which is what makes the patched output trustworthy, and then applied those same four hunks to current master rather than committing a document generated against an older revision, since the file moves daily.
The diff is exactly three $ref changes plus two schema definitions that had none before, because no desc had ever referenced ProjectScopeLink or GroupScopeLink. gitlab:openapi:v3:check_docs is the authority on that and will confirm it in this pipeline.
References
The endpoints are documented in doc/api/project_job_token_scopes.md, which already carries the correct response shapes.
Same class as !254699, which I opened today for two annotations in lib/api/projects.rb where the route names Entities::Group and the shared helper presents Entities::PublicGroupDetails. That is a different file and a different feature category, so the two are kept apart; a reviewer who wants them together is welcome to say so.
I found this while building a 1:1 comparison between the REST API and a GitLab client, where an entity annotation is read as the response contract. The wrong annotations put a project entity in front of a group response, which is the kind of mismatch a generated client cannot recover from on its own.
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 three
descblocks inlib/api/project_job_token_scope.rbagainst thepresentcall in each endpoint body immediately below them. - Against any instance, compare the two allowlist reads: the groups one answers with three keys and the projects one with seventeen. Then add a project and a group to a scope and observe that each creation answers with a two-key link object.
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.