OpenAPI: inline request bodies are emitted as anonymous RequestBody_<hash> schemas

Everyone can contribute. Help move this issue forward while earning points, leveling up and collecting rewards.

Summary

In doc/api/openapi/openapi_v3.yaml, request bodies defined inline on a route are hoisted into components/schemas under hash-based names like RequestBody_6ef4e663c0d4. There are 422 such schemas in the current spec. They have no semantic name and the hash changes whenever the body shape changes, so every code-generator that consumes this spec produces meaningless, version-unstable types.

Example

# components/schemas
RequestBody_6ef4e663c0d4:
  type: object
  properties:
    start_date: { type: string, format: date, nullable: true }
    end_date:   { type: string, format: date, nullable: true }
    plan_code:  { type: string }

This is the body of POST /api/v4/namespaces/{id}/gitlab_subscription, but nothing in the name says so. A typed client (e.g. Apple's swift-openapi-generator) turns it into Components.Schemas.RequestBody0f2b66d0bb55 — undiscoverable and unstable.

Impact

  • Discoverability: consumers can't tell what RequestBody_6ef4e663c0d4 is for.
  • Stability: the hash is derived from the body shape; any field change renames the type, breaking generated code across GitLab versions.
  • Ergonomics: generated SDKs expose RequestBody0f2b66d0bb55 instead of, say, CreateNamespaceSubscriptionRequest.
  • Scale: 422 occurrences — pervasive across the API.

Where it originates

Grape routes with inline params do … end blocks that aren't backed by a named params/entity class; lacking a name, the spec-generation tooling falls back to hashing the body shape.

Suggested fix

Give inline request bodies stable, semantic names derived from the operation (e.g. <OperationId>Request), either by naming the Grape params block, or by having the spec-generation tooling (gitlab-grape-openapi) derive the schema name from the route's operationId instead of hashing the body.

Reproduction

Search the spec for ^ RequestBody_[0-9a-f]+: → 422 matches; generate any typed client and observe the RequestBody<hash> type names. A spec asserting no hash-named schemas in components/schemas would prevent regressions.

Related

  • #519959, #591007 (closed) — context: OpenAPI v3 tooling and spec validation. Hash-named schemas are valid OpenAPI, so validation alone won't flag them.
  • Response-shape spec-accuracy defects found in the same strict-client run: #604895 (arrays), #604896 (scalars).
Edited by 🤖 GitLab Bot 🤖