Migrate API Page Content - Batch 11

Isaac Durhamrequested to merge
id/UpdateApiRetirementMergeRequests into master

What does this MR do?

This is one of a series of merge requests that moves content from the Markdown API pages under doc/api/** into the Grape source in lib/api/** and ee/lib/api/**. The Markdown pages are being retired in favor of api.gitlab.com/rest, so anything they say that the generated spec doesn't needs to move into the Ruby source first. That's operation descriptions, parameter descriptions, response field descriptions, and status codes. doc/api/openapi/openapi_v3.yaml is regenerated from these changes and included in this MR.

The files in this MR are covered only by the backend maintainers rule in CODEOWNERS, so any backend maintainer can approve it. They're grouped by product area: merge requests and review.

Review notes

Work list

File Endpoints Parameters Response fields
ee/lib/api/entities/approval_rule_short.rb 0 0 3
ee/lib/api/entities/approval_state.rb 0 0 16
ee/lib/api/entities/merge_trains/car.rb 0 0 10
ee/lib/api/group_approval_rules.rb 3 0 0
ee/lib/api/helpers/group_approval_rules_helpers.rb 0 1 0
ee/lib/api/merge_request_approval_rules.rb 1 0 0
ee/lib/api/merge_request_dependencies.rb 1 0 0
ee/lib/api/project_approval_rules.rb 2 0 0
ee/lib/api/project_approvals.rb 0 2 0
ee/lib/api/status_checks.rb 1 0 0
ee/lib/ee/api/entities/merge_request_basic.rb 0 0 1
ee/lib/ee/api/merge_request_approvals.rb 1 0 0
lib/api/discussions.rb 4 22 0
lib/api/draft_notes.rb 0 7 0
lib/api/entities/approvals.rb 0 0 2
lib/api/entities/commit_note.rb 0 0 6
lib/api/entities/diff.rb 0 0 11
lib/api/entities/diff_refs.rb 0 0 3
lib/api/entities/diff_stat.rb 0 0 4
lib/api/entities/discussion.rb 0 0 3
lib/api/entities/merge_request.rb 0 0 14
lib/api/entities/merge_request_author.rb 0 0 1
lib/api/entities/merge_request_basic.rb 0 0 46
lib/api/entities/merge_request_diff.rb 0 0 9
lib/api/entities/merge_request_diff_full.rb 0 0 2
lib/api/entities/merge_request_simple.rb 0 0 2
lib/api/entities/note.rb 0 0 16
lib/api/entities/suggestion.rb 0 0 7
lib/api/helpers/merge_requests_helpers.rb 0 6 0
lib/api/merge_request_approvals.rb 3 0 0
lib/api/merge_requests.rb 11 2 0
lib/api/notes.rb 1 7 0

28 endpoints, 47 parameters and 156 response fields changed across 32 files.

What the columns mean. Endpoints is how many route desc blocks changed, for detail text, success or failure codes, or a deprecated flag. Parameters is how many requires/optional declarations got new desc: text. Response fields is how many entity expose lines got a description in their documentation hash.

Review record

Each fact was checked against the endpoint's handler code before it went in. Where the Markdown and the code disagreed, the code won and the Markdown fact was left out. After the spec was regenerated, an automated check compared each Markdown page against it and confirmed the fact now appears. Both checks look for the fact, not for how well it reads, so check the new wording against the endpoint it serves, and flag anything that reads wrong or drops something the old text had.

rubocop and the docs lint pass on this branch.

Review notes for this MR

  • Only documentation changed. desc, detail, success, failure and deprecated inside a route's desc block, and the documentation hash on entity expose lines, only feed the generated spec. Nothing changes how a request is handled or what a response contains.
  • Where one description serves several endpoints or generated params, the text is built once in a constant or local, for example noteable_id_desc in lib/api/discussions.rb. These only feed desc and detail.
  • deprecated true is added to routes the Markdown already marks as deprecated, in lib/api/merge_requests.rb. It only sets deprecated in the spec.
  • Suggest any wording change in the Ruby files, not in doc/api/openapi/openapi_v3.yaml. The YAML is generated from the Ruby, so edits made there get overwritten.
  • One desc: can be shared by several endpoints, so a single wording change may show up in more than one place in the generated spec.
  • Some status codes and param types the Markdown lists are still missing from the spec. Those come in later MRs, tracked in #639428.
  • doc/api/openapi/openapi_v3.yaml is regenerated and included. openapi_v2.yaml is not touched and stays stale on purpose, tracked separately.

Related issues

🤖 Generated with Claude Code

Edited by Isaac Durham

Merge request reports