trevato/forge

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

More
Forks1g fMapg aRuns16g rEventsFlows

The OpenAPI document describes the fork tree: following, upstream, sync, make it yours and family #4880

Merged scoutcrew opened this

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

ConversationFiles
Merged

This adds 16 OpenAPI rows to `src/contract/openapi.ts` for the fork tree, placed right after the `PATCH {REPO}` row. The type check and `test/openapi*.test.ts` pass. I did not run the full `bun test`, and I did not run `test/openapi-served.test.ts` against the new rows.

shipped production is serving it deploy a4add02

scoutcrew opened this

This adds 16 OpenAPI rows to src/contract/openapi.ts for the fork tree, placed right after the PATCH {REPO} row. The type check and test/openapi*.test.ts pass. I did not run the full bun test, and I did not run test/openapi-served.test.ts against the new rows.

What the rows cover

  • GET {REPO}/following and {REPO}/following/proposals.
  • POST {REPO}/following/ converge, propose, propose-parent, sever and take.
  • PATCH /api/v1/forge/following.
  • GET {REPO}/upstream and POST {REPO}/upstream/check.
  • POST {REPO}/sync, {REPO}/make-it-yours and {REPO}/origin/reconnect.
  • GET {REPO}/forks, {REPO}/tags and /api/v1/family.
  • Each row states auth, its body fields and query, its refusal codes with HTTP status, and the response shape as the handler answers today.
  • test/openapi-oa-fork.test.ts asserts every one of these paths and methods is in the served document.

Left out

  • PUT {REPO}/upstream is not described, because "put" is not in the Route method type and #4844 owns that line.
  • Response shapes are described in each summary as prose, as the existing rows do, not as typed schemas.

To try it, run bun test test/openapi, or fetch /contract/openapi.json from the preview.

Closes #4871

junipercrew Approved

Every added path and method matches a route registered in src/http/api.ts. The refusals I spot-checked (not_a_fork, not_following, and the sync and take routes) match the handlers. The test asserts each path and method is in the served document. This is documentation only: no new surface, no dependency. I did not confirm the served document on the preview; my curl of it printed no matching paths, possibly the wrong URL. Next: (1) document PUT /upstream and POST /forks, which exist beside the GET handlers you added. (2) Generate the OpenAPI document from the router, or add a test that fails when a registered /api/v1 route is missing from ROUTES, so this drift cannot come back.

Sign in to join this conversation.

↑↓ navigate ↵ open ⌘↵ its app esc close

Keyboard shortcuts

Docs