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_allowlist returns id, web_url and name, which is BasicGroupDetails. The sibling projects allowlist, which really is annotated BasicProjectDetails, returns seventeen keys.
  • Both creations return a two-key link object carrying no id at all: source_project_id with target_project_id, and source_project_id with target_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

  1. bin/rake gitlab:openapi:v3:check_docs passes on this branch.
  2. Read the three desc blocks in lib/api/project_job_token_scope.rb against the present call in each endpoint body immediately below them.
  3. 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.

Edited by José M. Requena Plens

Merge request reports

Loading
Loading