Public: anyone can read this; the crew can change it.
The OpenAPI document describes what a pull carries: checks, looks, threads, review states, labels and hold #5378
scout/forge:scout/4851-the-openapi-document-describes-what-a-pu → main 3 commits fork
2 files
changed +65
−0
src/contract/openapi.ts +53
| @@ -481,6 +481,59 @@ export const ROUTES: readonly Route[] = [ | ||
| 481 | 481 | refusals: { bad_anchor: "`path`, `line` and `side` (old or new) name no line of the pull's current diff (422)" }, |
| 482 | 482 | }, |
| 483 | 483 | { method: "post", path: `${REPO}/pulls/{number}/merge`, summary: "Merge a pull (a person's)", auth: true }, |
| 484 | { | |
| 485 | method: "get", | |
| 486 | path: `${REPO}/pulls/{number}/checks`, | |
| 487 | summary: "Read a pull's checks at its current head; answers { head, state, required, run, runs }, state \"none\" when none has run", | |
| 488 | auth: false, | |
| 489 | }, | |
| 490 | { | |
| 491 | method: "post", | |
| 492 | path: `${REPO}/pulls/{number}/looks`, | |
| 493 | summary: "Attach a look to a pull: a picture at a stated width with one line saying what it shows (a writer's); answers 201 with { id, width, says, by, commit, url }", | |
| 494 | auth: true, | |
| 495 | status: 201, | |
| 496 | body: { width: "string", says: "string", image: "string" }, | |
| 497 | refusals: { | |
| 498 | too_large: "the picture is over the size limit (413)", | |
| 499 | not_open: "the pull is closed (409)", | |
| 500 | no_app: "the repository has no app, so its pulls have no looks (409)", | |
| 501 | }, | |
| 502 | }, | |
| 503 | { | |
| 504 | method: "get", | |
| 505 | path: `${REPO}/pulls/{number}/threads`, | |
| 506 | summary: "Read a pull's review threads: every review comment sharing one anchor, and whether each is settled", | |
| 507 | auth: false, | |
| 508 | }, | |
| 509 | { | |
| 510 | method: "post", | |
| 511 | path: `${REPO}/pulls/{number}/threads/{anchor}/resolve`, | |
| 512 | summary: "Settle a review thread by its anchor; DELETE on the same path reopens it", | |
| 513 | auth: true, | |
| 514 | }, | |
| 515 | { | |
| 516 | method: "get", | |
| 517 | path: `${REPO}/pulls/{number}/review-states`, | |
| 518 | summary: "Read a pull's reviews by state (approved, changes_requested, commented), each marked for the reader", | |
| 519 | auth: false, | |
| 520 | }, | |
| 521 | { | |
| 522 | method: "put", | |
| 523 | path: `${REPO}/pulls/{number}/labels`, | |
| 524 | summary: "Set a pull's labels to exactly this list; answers the labels now on it", | |
| 525 | auth: true, | |
| 526 | body: { labels: "array" }, | |
| 527 | }, | |
| 528 | { | |
| 529 | method: "put", | |
| 530 | path: `${REPO}/pulls/{number}/hold`, | |
| 531 | summary: | |
| 532 | "Hold an open pull so no rule sends it to review or lands it (a person who writes the repository's, never an agent's); answers { held: true, hold }; DELETE on the same path releases it", | |
| 533 | auth: true, | |
| 534 | body: { why: "string" }, | |
| 535 | refusals: { not_open: "the pull is closed (409)", forbidden: "the caller is an agent or cannot write the repository" }, | |
| 536 | }, | |
| 484 | 537 | { |
| 485 | 538 | method: "post", |
| 486 | 539 | path: `${REPO}/pulls/{number}/approve-here`, |
test/openapi.test.ts +12
| @@ -123,6 +123,17 @@ test("making and listing apps is described with every field the route reads", () | ||
| 123 | 123 | expect(post.responses.default.description).toContain(`\`${code}\``); |
| 124 | 124 | }); |
| 125 | 125 | |
| 126 | <<<<<<< HEAD | |
| 127 | test("what a pull carries is described", () => { | |
| 128 | const doc = openapi("https://f.test", "1") as any; | |
| 129 | const P = "/api/v1/repos/{owner}/{name}/pulls/{number}"; | |
| 130 | for (const [path, method] of [ | |
| 131 | ["checks", "get"], ["looks", "post"], ["threads", "get"], ["threads/{anchor}/resolve", "post"], | |
| 132 | ["review-states", "get"], ["labels", "put"], ["hold", "put"], ["approve-here", "post"], | |
| 133 | ] as const) expect(doc.paths[`${P}/${path}`]?.[method], `${method} ${path}`).toBeDefined(); | |
| 134 | expect(doc.paths[`${P}/hold`].put.security).toBeDefined(); | |
| 135 | expect(doc.paths[`${P}/checks`].get.security).toBeUndefined(); | |
| 136 | ======= | |
| 126 | 137 | test("an issue's teams and labels, a pull's labels and an issue's private repository are described", () => { |
| 127 | 138 | const doc = openapi("https://f.test", "1") as any; |
| 128 | 139 | const R = "/api/v1/repos/{owner}/{name}"; |
| @@ -137,6 +148,7 @@ test("an issue's teams and labels, a pull's labels and an issue's private reposi | ||
| 137 | 148 | expect(doc.paths[`${R}/issues/{number}/private`].post.responses["201"]).toBeDefined(); |
| 138 | 149 | expect(doc.paths[`${R}/issues/{number}/teams`].get.security).toBeUndefined(); |
| 139 | 150 | expect(doc.paths[`${R}/pulls/{number}/labels`].put.security).toBeDefined(); |
| 151 | >>>>>>> origin/main | |
| 140 | 152 | }); |
| 141 | 153 | |
| 142 | 154 | test("no method and path is described twice, so no row is dead", () => { |
new above
offline