[Schema Inaccuracy] *-roles list endpoints missing per_page/page params despite live API paginating

[aepifano-square]

Schema Inaccuracy

Four *-roles list endpoints declare only path parameters in their spec definitions, but GitHub's live API honors per_page/page and returns standard Link: rel="next" pagination headers. Without the query params declared, OpenAPI-generated clients silently fetch page 1 only — a correctness regression once an org accumulates more than 30 roles.

Affected endpoints (all GET):

1. /orgs/{org}/organization-roles (orgs/list-org-roles) — api.github.com and ghec
2. /organizations/{organization_id}/custom_roles (orgs/list-custom-roles) — ghec only
3. /orgs/{org}/custom-repository-roles (orgs/list-custom-repo-roles) — ghec only
4. /enterprises/{enterprise}/enterprise-roles (enterprise-admin/list-enterprise-roles) — ghec only

Currently each declares only its path param, e.g.:

"parameters": [
  { "$ref": "#/components/parameters/org" }
]

The REST docs for these endpoints likewise omit the pagination parameters section, in contrast with sibling endpoints on the same docs page (e.g. "List teams that are assigned to an organization role" — /orgs/{org}/organization-roles/{role_id}/teams) which correctly declare and document per_page/page.

Expected

Each affected endpoint's parameters array should include the canonical pagination refs — matching every other paginated endpoint in the spec, including the sibling at /orgs/{org}/organization-roles/{role_id}/teams:

"parameters": [
  { "$ref": "#/components/parameters/org" },
  { "$ref": "#/components/parameters/per-page" },
  { "$ref": "#/components/parameters/page" }
]

(Substitute enterprise / organization-id for the path-param ref on each respective endpoint.)

Reproduction Steps

/orgs/{org}/organization-roles returns a Link header at per_page=1 despite the spec not declaring per_page/page:

$ gh api -i "/orgs/<org>/organization-roles?per_page=1" 2>&1 | grep -E "^(HTTP|Link)"
HTTP/2.0 200 OK
Link: <https://api.github.com/organizations/<org_id>/organization-roles?per_page=1&page=2>; rel="next", <https://api.github.com/organizations/<org_id>/organization-roles?per_page=1&page=12>; rel="last"

page is honored too — page=2 returns rel="prev" and rel="next" links:

$ gh api -i "/orgs/<org>/organization-roles?per_page=1&page=2" 2>&1 | grep "^Link"
Link: <...?per_page=1&page=1>; rel="prev", <...?per_page=1&page=3>; rel="next", <...?per_page=1&page=12>; rel="last", <...?per_page=1&page=1>; rel="first"

The other three endpoints exhibit the same Link rel="prev" behavior on page=2 against an org with at least one role/custom-role:

$ gh api -i "/organizations/<org_id>/custom_roles?per_page=1&page=2" 2>&1 | grep "^Link"
Link: <...?per_page=1&page=1>; rel="prev", <...?per_page=1&page=1>; rel="last", <...?per_page=1&page=1>; rel="first", ...

$ gh api -i "/orgs/<org>/custom-repository-roles?per_page=1&page=2" 2>&1 | grep "^Link"
Link: <...?per_page=1&page=1>; rel="prev", <...?per_page=1&page=1>; rel="last", <...?per_page=1&page=1>; rel="first"

The spec declares only the path param across all four:

$ curl -s https://raw.githubusercontent.com/github/rest-api-description/main/descriptions/ghec/ghec.2022-11-28.json \
    | jq '.paths["/orgs/{org}/organization-roles"].get.parameters'
[
  {
    "$ref": "#/components/parameters/org"
  }
]

Same single-path-param shape for the other three endpoints.

Consumer Impact

OpenAPI-generated clients that infer pagination from declared per_page/page query parameters (the standard signal across the rest of the spec) will treat these endpoints as single-shot. Consumers that iterate organization roles to perform cleanup or audit operations will silently miss every role beyond page 1 — defaulting to page size 30, but as small as 1 if the client passes per_page=1 for cost reasons. This is undetectable without a separate Link-header check, since the response body itself is well-formed and the total_count field can easily be mistaken for "size of this response" rather than "total across all pages".