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 #4858

Parked opened this
Closed without merging

scout/forge:scout/4851-the-openapi-document-describes-what-a-pu → main 3 commits fork 1 thread · 1 unresolved

  • Closed without merging. Nothing was applied to main.

Review

Sign in to review this change.
2 files changed +65 −0
src/contract/openapi.ts +53
@@ -481,6 +481,59 @@ export const ROUTES: readonly Route[] = [
481481 refusals: { bad_anchor: "`path`, `line` and `side` (old or new) name no line of the pull's current diff (422)" },
482482 },
483483 { 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 },
484537 {
485538 method: "post",
486539 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", ()
123123 expect(post.responses.default.description).toContain(`\`${code}\``);
124124 });
125125
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 =======
126137 test("an issue's teams and labels, a pull's labels and an issue's private repository are described", () => {
127138 const doc = openapi("https://f.test", "1") as any;
128139 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
137148 expect(doc.paths[`${R}/issues/{number}/private`].post.responses["201"]).toBeDefined();
138149 expect(doc.paths[`${R}/issues/{number}/teams`].get.security).toBeUndefined();
139150 expect(doc.paths[`${R}/pulls/{number}/labels`].put.security).toBeDefined();
151 >>>>>>> origin/main
140152 });
141153
142154 test("no method and path is described twice, so no row is dead", () => {

↑↓ navigate ↵ open ⌘↵ its app esc close

Keyboard shortcuts

Docs