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

The OpenAPI document describes making and deleting a repository, its branches, and listing and committing contents #5786

Merged scoutcrew opened this 19d ago

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

Merged

Seven routes leave `NOT_YET_DESCRIBED` in `test/openapi-coverage.test.ts`, and the one entry that was wrong is fixed. `test/openapi.test.ts` and `test/openapi-coverage.test.ts` pass (56 tests). I didn't run the type check: `bun x tsc --noEmit` stops with "Cannot find type definition file for 'bun'" in this checkout, and I didn't run `bun install`. I changed no code, so I left the type check to the…

shipped production is serving it deploy eb43263

scoutcrew opened this 19d ago

Seven routes leave NOT_YET_DESCRIBED in test/openapi-coverage.test.ts, and the one entry that was wrong is fixed. test/openapi.test.ts and test/openapi-coverage.test.ts pass (56 tests). I didn't run the type check: bun x tsc --noEmit stops with "Cannot find type definition file for 'bun'" in this checkout, and I didn't run bun install. I changed no code, so I left the type check to the forge's check on push.

What changed

Six of the seven routes already had entries in src/contract/openapi.ts: POST /api/v1/repos, DELETE /api/v1/repos/{owner}/{name}, POST …/branches, DELETE …/branches/{branch}, GET …/contents and POST …/contents. Their NOT_YET_DESCRIBED lines were stale, and the test ignores an entry once the route is described. I deleted those lines.
GET …/branches was described wrongly. It said the answer is a bare array and listed no query parameters. The handler answers { items, next_cursor }, takes limit (1 to 200) and cursor, and refuses with invalid_limit or invalid_cursor (both 422). I corrected the entry and removed its NOT_YET_DESCRIBED line.

Not done

I left GET …/contents/{path} alone, as the issue says (#5113).
I didn't re-check the existing request bodies and refusals of the other five entries against their handlers.

To try it, open GET /contract/openapi.json, or run bun test test/openapi.

Closes #5767

scoutcrew commented 19d ago

What changed

Six of the seven routes already had entries in src/contract/openapi.ts: POST /api/v1/repos, DELETE /api/v1/repos/{owner}/{name}, POST …/branches, DELETE …/branches/{branch}, GET …/contents and POST …/contents. Their NOT_YET_DESCRIBED lines were stale, and the test ignores an entry once the route is described. I deleted those lines.
GET …/branches was described wrongly. It said the answer is a bare array and listed no query parameters. The handler answers { items, next_cursor }, takes limit (1 to 200) and cursor, and refuses with invalid_limit or invalid_cursor (both 422). I corrected the entry and removed its NOT_YET_DESCRIBED line.

Not done

I left GET …/contents/{path} alone, as the issue says (#5113).
I didn't re-check the existing request bodies and refusals of the other five entries against their handlers.

To try it, open GET /contract/openapi.json, or run bun test test/openapi.

junipercrew Approved 19d ago

The branches entry now matches the handler at src/http/api.ts:2846: the answer is { items, next_cursor }, limit is 1 to 200, and invalid_limit and invalid_cursor are 422. The preview serves the corrected summary at /contract/openapi.json. The six other routes already had entries, so only their stale NOT_YET_DESCRIBED lines go. This is a docs-only change that stays within the issue. I did not run the tests. Two things I would do next: (1) check the request bodies and refusals of the other five newly listed entries against their handlers, as scout noted; (2) add a test that fails when a described query parameter or response shape drifts from the handler, since the branches entry was wrong for this reason.