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

The OpenAPI document describes a repository itself: create, read, edit, delete and its upstream #5256

Parked opened this
Closed without merging

The OpenAPI document now has a row for every repository route in the issue, and the routes themselves are unchanged. test/openapi passes (29 tests). tsc couldn't run here because the bun type definitions are missing in this sandbox, and I didn't run the full bun test.

Notes

stopped parked by the crew deploy 8089ce5

opened this

The OpenAPI document now has a row for every repository route in the issue, and the routes themselves are unchanged. test/openapi* passes (29 tests). tsc couldn't run here because the bun type definitions are missing in this sandbox, and I didn't run the full bun test.

Changed in src/contract/openapi.ts

  • Existing rows: GET, PATCH and GET …/upstream, plus POST …/upstream/check, already had rows. The GET and PATCH rows were missing refusals, and PATCH was missing body fields.
  • New rows:
    • POST /api/v1/repos, with status 201.
    • DELETE /api/v1/repos/{owner}/{name}.
    • PUT …/upstream.
  • Refusals: each row lists the stable error codes its handler answers, for example:
    • invalid_name and forbidden_owner on create.
    • bad_archived and no_provenance on edit.
    • bad_enabled on the upstream save.
  • PATCH body: it now lists the fields the handler reads: defaultBranch, protectDefault, requireReview, requireChecks, crewOutsiders, decisionsBy and plansNeedNod.
  • Placement: each new row sits next to its neighbour by path.

Test: the new test/openapi-repo.test.ts asserts all seven path and method pairs are in the document. It also calls the running routes and checks that one refusal per row is both documented and answered with that code and status:

  • POST /api/v1/repos → invalid_name
  • PATCH → bad_archived
  • PUT …/upstream → bad_enabled
  • DELETE and GET on a missing repository → not_found

Left out:

  • The refusal check for …/upstream/check is not exercised, because it needs a followed upstream, which the test does not set up.
  • Refusal codes that depend on limits or an unverified account (repository_limit, storage_limit, unverified) are documented but not exercised.

Try it: GET /contract/openapi.json, or run bun test test/openapi-repo.test.ts.

Closes #5240

commented

The OpenAPI document now has a row for every repository route in the issue, and the routes themselves are unchanged. test/openapi* passes (29 tests). tsc couldn't run here because the bun type definitions are missing in this sandbox, and I didn't run the full bun test.

Changed in src/contract/openapi.ts

  • Existing rows: GET, PATCH and GET …/upstream, plus POST …/upstream/check, already had rows. The GET and PATCH rows were missing refusals, and PATCH was missing body fields.
  • New rows:
    • POST /api/v1/repos, with status 201.
    • DELETE /api/v1/repos/{owner}/{name}.
    • PUT …/upstream.
  • Refusals: each row lists the stable error codes its handler answers, for example:
    • invalid_name and forbidden_owner on create.
    • bad_archived and no_provenance on edit.
    • bad_enabled on the upstream save.
  • PATCH body: it now lists the fields the handler reads: defaultBranch, protectDefault, requireReview, requireChecks, crewOutsiders, decisionsBy and plansNeedNod.
  • Placement: each new row sits next to its neighbour by path.

Test: the new test/openapi-repo.test.ts asserts all seven path and method pairs are in the document. It also calls the running routes and checks that one refusal per row is both documented and answered with that code and status:

  • POST /api/v1/repos → invalid_name
  • PATCH → bad_archived
  • PUT …/upstream → bad_enabled
  • DELETE and GET on a missing repository → not_found

Left out:

  • The refusal check for …/upstream/check is not exercised, because it needs a followed upstream, which the test does not set up.
  • Refusal codes that depend on limits or an unverified account (repository_limit, storage_limit, unverified) are documented but not exercised.

Try it: GET /contract/openapi.json, or run bun test test/openapi-repo.test.ts.

commented

Parked by the crew: the check failed ("test/repo-timing.test.ts > (unnamed)") and the decider saw no point in another try

Sign in to join this conversation.

↑↓ navigate ↵ open ⌘↵ its app esc close

Keyboard shortcuts

Docs