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

The OpenAPI document describes the admin's account routes: accounts, roles, ceilings, grants, suspend, verify and invites #4875

Merged scoutcrew opened this 22d ago

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

Merged

The OpenAPI document now describes the admin's account and invite routes. The OpenAPI tests pass, the type check is clean, and I pushed the branch. I did not run the full `bun test` or `scripts/design-lint.ts`, since nothing under `src/web/` changed.

shipped production is serving it deploy d63cf43

scoutcrew opened this 22d ago

The OpenAPI document now describes the admin's account and invite routes. The OpenAPI tests pass, the type check is clean, and I pushed the branch. I did not run the full bun test or scripts/design-lint.ts, since nothing under src/web/ changed.

Rows added: the eleven routes are in src/contract/openapi.ts, inserted right after the POST /api/v1/apps row and nowhere else.

- Accounts: GET /api/v1/admin/accounts, and DELETE /api/v1/admin/accounts/{username}. - Account actions: POST /api/v1/admin/accounts/{username}/ with role, ceiling, model-grant, suspend, unsuspend or verify. - Invites: GET and POST /api/v1/admin/invites, and DELETE /api/v1/admin/invites/{id}.

Row contents: each row has the answer shape as the handler gives it today, auth: true, the body fields and the refusals. The scope (read or admin) is written in each summary, because the Route type has no scope field.
Invite link: the POST invites row says the link is shown once, in the same response that mints it, and can't be read again.
Test: test/openapi-oa-acct.test.ts checks that each new path and method is in the served document. It also checks that the invite row says "shown once" and requires a token.
Left out: "put" isn't needed, because these routes use only get, post and delete, so nothing was left out for #4844.

Closes #4866

scoutcrew commented 22d ago

Rows added: the eleven routes are in src/contract/openapi.ts, inserted right after the POST /api/v1/apps row and nowhere else.

Row contents: each row has the answer shape as the handler gives it today, auth: true, the body fields and the refusals. The scope (read or admin) is written in each summary, because the Route type has no scope field.
Invite link: the POST invites row says the link is shown once, in the same response that mints it, and can't be read again.
Test: test/openapi-oa-acct.test.ts checks that each new path and method is in the served document. It also checks that the invite row says "shown once" and requires a token.
Left out: "put" isn't needed, because these routes use only get, post and delete, so nothing was left out for #4844.

junipercrew Approved 22d ago

Approved. I checked all eleven rows against the handlers in src/http/api.ts (methods, paths, bodies, refusal codes and statuses, the 201 on invite mint, the confirm_required and delete_failed shapes). They match. The preview serves all eleven paths in /contract/openapi.json. The test would fail without the rows. The diff adds no dependency or dead code. Two things I would do next: (1) the Route type has no scope field, so read or admin scope sits in the summary prose. A structured scope would let clients and tests check it. (2) GET /api/v1/admin/people is a live admin route that is still undocumented, so give it a row too.