Migrate API Params - Batch 6

Isaac Durhamrequested to merge
id/PortParamDescriptions/6 into master

What does this MR do?

This is one of a series of merge requests that replaces the desc: text on Grape REST API parameter declarations (requires and optional) in lib/api/** and ee/lib/api/** with wording standardized from the hand-written Markdown under doc/api/**. The Markdown pages are being retired in favor of api.gitlab.com/rest, so any wording that only lives in Markdown needs to move into the Ruby source before it's lost for good. doc/api/openapi/openapi_v3.yaml is regenerated from these changes and included in this MR.

Review notes

Work list

File Parameters desc: lines changed Endpoints Descriptions in the spec
ee/lib/api/admin/data_management.rb 5 8 4 8
ee/lib/api/ai/duo_workflows/agent_workflows.rb 16 14 1 16
ee/lib/api/ai/duo_workflows/workflows.rb 19 30 5 22
ee/lib/api/ai/duo_workflows/workflows_internal.rb 29 40 11 41
ee/lib/api/audit_events.rb 5 6 2 5
ee/lib/api/chat.rb 17 14 1 17
ee/lib/api/group_hooks.rb 31 34 12 74
ee/lib/api/manage/groups.rb 9 14 8 20
ee/lib/api/security/vulnerability_scanning/sbom_scans.rb 5 9 4 8
ee/lib/ee/api/deployments.rb 5 5 1 5
ee/lib/ee/api/helpers/protected_branches_helpers.rb 1 1 4 4
ee/lib/ee/api/merge_request_approvals.rb 3 3 2 5
ee/lib/ee/api/namespaces.rb 17 10 3 17
ee/lib/ee/api/projects.rb 3 3 2 3
ee/lib/ee/api/search/semantic_code_search.rb 3 3 1 3
lib/api/admin/batched_background_migrations.rb 3 10 4 8
lib/api/admin/batched_background_operations.rb 3 5 4 8
lib/api/admin/plan_limits.rb 30 31 2 31
lib/api/alert_management_alerts.rb 3 4 5 12
lib/api/applications.rb 5 4 3 6
lib/api/award_emoji.rb 4 4 32 72
lib/api/boards_responses.rb 3 3 2 5
lib/api/clusters/agent_tokens.rb 5 6 4 12
lib/api/clusters/agents.rb 3 4 4 7
lib/api/composer_packages.rb 4 6 4 7
lib/api/custom_attributes_endpoints.rb 3 3 12 24
lib/api/deployments.rb 9 14 6 21
lib/api/error_tracking/project_settings.rb 3 5 3 7
lib/api/feature_flags_user_lists.rb 5 7 5 13
lib/api/group_boards.rb 4 8 9 20
lib/api/group_export.rb 4 6 5 10
lib/api/group_labels.rb 9 16 7 22
lib/api/helm_packages.rb 3 6 4 9
lib/api/helpers/events_helpers.rb 5 5 2 10
lib/api/integrations.rb 2 4 165 165
lib/api/integrations/integratable_operations.rb 1 2 6 6
lib/api/labels.rb 7 15 9 23
lib/api/members.rb 10 16 14 46
lib/api/ml/mlflow/entrypoint.rb 1 1 28 28
lib/api/ml/mlflow/runs.rb 23 27 9 33
lib/api/ml/mlflow_artifacts/artifacts.rb 1 1 1 1
lib/api/ml/mlflow_artifacts/entrypoint.rb 1 1 1 1
lib/api/npm_group_packages.rb 1 1 2 2
lib/api/nuget_group_packages.rb 1 1 4 4
lib/api/nuget_project_packages.rb 2 3 12 13
lib/api/offline_transfers.rb 31 32 4 53
lib/api/organizations.rb 1 1 1 1
lib/api/project_avatar.rb 1 1 1 1
lib/api/project_debian_distributions.rb 1 1 6 6
lib/api/project_service_accounts.rb 11 17 8 27
lib/api/project_statistics.rb 1 1 1 1
lib/api/releases.rb 21 34 7 37
lib/api/resource_label_events.rb 2 2 6 9
lib/api/resource_milestone_events.rb 3 4 4 10
lib/api/resource_state_events.rb 2 2 6 9
lib/api/rpm_project_packages.rb 1 1 2 2
lib/api/service_accounts.rb 6 9 3 9
lib/api/subscriptions.rb 2 2 8 16
lib/api/suggestions.rb 3 4 2 4
lib/api/supply_chain/attestations.rb 3 3 2 4
lib/api/terraform/state_protection_rules.rb 5 7 4 10
lib/api/time_tracking_endpoints.rb 1 2 4 4

546 desc: lines changed across 62 files, on 481 endpoints, producing 1077 description changes in openapi_v3.yaml.

What the columns mean. Parameters is how many distinct parameter names the file touches. desc: lines changed is how many requires/optional declarations got new text, which is what you see in the Ruby diff. Descriptions in the spec is larger than that, because one declaration in a shared block supplies the description for every endpoint that uses it: id in lib/api/commits.rb is a single line serving 12 endpoints.

Full Worklist is available here.

Review record

These descriptions haven't been through the one-at-a-time review the earlier batch had, so you're the first person checking this wording against the docs. 18 of 452 review units were checked, covering 64 of 1034 descriptions in the generated spec; the gap between those two figures is because a single reviewed wording can supply the description for many endpoints, so a small number of checked units can cover a disproportionate share of the spec. Weight your read accordingly: check the new wording against the endpoint it serves, and flag anything that reads wrong or drops a fact the old text had. An automated audit compared each new description against its source text and found nothing in its three blocking severities, and a wording-policy check enforces house sentence patterns and US spelling, but both check form rather than meaning, so they don't substitute for reading.

A verification step regenerated the specification and confirmed it changed exactly the entries expected and nothing else.

Review notes for this MR

  • Only desc: strings changed on Grape requires/optional declarations. type:, values:, default: and documentation: are untouched, so there's no behaviour change here.
  • Suggest any wording change in the lib/api/** and ee/lib/api/** Ruby files, not in doc/api/openapi/openapi_v3.yaml. The YAML is generated from the Ruby, so edits made there get overwritten.
  • Structured details like default: and values: are deliberately left out of the prose. The spec already carries them in their own fields, so their absence from a desc: is not an omission to flag.
  • 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.
  • 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

Merge request reports