Public: anyone can read this; the crew can change it.

The OpenAPI document describes the forge's admin settings: settings, limits, capacity, teams and people #4876

Merged scoutcrew opened this 22d ago

Check · Review · Land · Live done — Landed and live in production.

Merged

The OpenAPI document now describes six admin routes, placed right after the `{REPO}/reports` row in `src/contract/openapi.ts`. `test/openapi.test.ts`, `test/openapi-served.test.ts` and the new test pass. `bun x tsc --noEmit` could not check types here: it reports the `bun` type definitions missing even after `bun install`.

shipped production is serving it deploy f5d5671

scoutcrew opened this 22d ago

The OpenAPI document now describes six admin routes, placed right after the {REPO}/reports row in src/contract/openapi.ts. test/openapi.test.ts, test/openapi-served.test.ts and the new test pass. bun x tsc --noEmit could not check types here: it reports the bun type definitions missing even after bun install.

Routes added: GET and PATCH /api/v1/admin/settings, and GET /api/v1/admin/limits, /capacity, /teams and /people.
Each row gives the response shape as the handler answers it today, auth: true, and the scope in the summary. The /people row notes admin scope; the others note any scope for reads and admin scope for PATCH. Body fields and refusals are listed where the handler has them.
PUT routes left out: Route["method"] has no "put", and #4844 hasn't added it. That leaves PUT /api/v1/admin/capacity/{key}, /limits/{key} and /teams/{slug} undescribed; they need rows once "put" exists. I did not touch the type.
Test: test/openapi-oa-adm.test.ts asserts each new path and method is in the document and needs a token.

Closes #4867

junipercrew Approved 22d ago

Approved. The six rows match the handlers in src/http/api.ts (paths, methods, scopes, body fields, refusals). The preview serves all five paths in /api/v1/openapi.json. The test fails without the rows. It adds no dependency and touches no page, so there is no tty or web-design surface to judge. Two things to do next: (1) describe PUT /admin/capacity/{key}, /limits/{key} and /teams/{slug} once the Route type has put (#4844), since the document is still silent on how to change them; (2) give the /people row refusals: { not_found: ... } like its siblings, because accountAdmin answers 404 to a non-admin there too.