Public: anyone can read this; the crew can change it.
The OpenAPI document describes a repository's reads: branches, commits, contents, labels and milestones #4856
Check · Review · Land · Live done — Landed and live in production.
scout/forge:scout/4846-the-openapi-document-describes-a-reposit → main 3 commits fork
2 files
changed +18
−0
src/contract/openapi.ts +7
| @@ -249,6 +249,13 @@ export const ROUTES: readonly Route[] = [ | ||
| 249 | 249 | }, |
| 250 | 250 | { method: "get", path: `${REPO}/issues`, summary: "List a repository's issues; fields=brief leaves out bodies and comments, any other fields value is a 422 invalid_fields", auth: false, query: { ...LIST_QUERY, fields: "string" } }, |
| 251 | 251 | { method: "get", path: `${REPO}/pulls`, summary: "List a repository's pulls", auth: false, query: LIST_QUERY }, |
| 252 | { method: "get", path: `${REPO}/branches`, summary: "List a repository's branches as a bare array of { name, oid, isDefault, ahead, behind, protected }; ahead and behind are null past the comparison cap; a private repository needs a token", auth: false }, | |
| 253 | { method: "get", path: `${REPO}/commits`, summary: "List commits newest first from `ref` (default: the default branch) as a bare array of { oid, parents, author, email, date, subject, body }; limit 1 to 100 (default 30); an unsafe ref is a 422 bad_ref; a private repository needs a token", auth: false, query: { ref: "string", limit: "integer" } }, | |
| 254 | { method: "get", path: `${REPO}/commits/{oid}`, summary: "Read one commit (a full or abbreviated id, or a ref) as { oid, parents, author, email, date, subject, body, diff: { files, additions, deletions } }; a private repository needs a token", auth: false }, | |
| 255 | { method: "get", path: `${REPO}/contents`, summary: "Read the tree or a file at `ref` (default: the default branch); no `path` or a directory answers { type: \"dir\", ref, path, entries }, a file answers { type: \"file\", ref, path, size, encoding: \"utf-8\" | \"base64\", content }, a file over 5 MB is a 413 { type: \"file\", tooLarge: true, size }; a private repository needs a token", auth: false, query: { path: "string", ref: "string" } }, | |
| 256 | { method: "get", path: `${REPO}/labels`, summary: "List a repository's labels by name as a bare array of { id, name, color }; a private repository needs a token", auth: false }, | |
| 257 | { method: "get", path: `${REPO}/milestones`, summary: "Read the plan: { repo: { owner, name }, limbs }, one limb per milestone with its weights (and askToLive for a pillar's umbrella); a private repository needs a token", auth: false }, | |
| 258 | { method: "get", path: `${REPO}/milestones/{number}`, summary: "Read one milestone (a 404 for an issue that waits for nothing) as { repo, ...milestone, askToLive?, watching? }; watching is present only for a signed-in user; a private repository needs a token", auth: false }, | |
| 252 | 259 | { |
| 253 | 260 | method: "post", |
| 254 | 261 | path: `${REPO}/issues`, |
test/openapi.test.ts +11
| @@ -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 | test("a repository's reads are described: branches, commits, contents, labels, milestones", () => { | |
| 127 | const doc = openapi("https://f.test", "1") as any; | |
| 128 | const R = "/api/v1/repos/{owner}/{name}"; | |
| 129 | for (const path of ["branches", "commits", "commits/{oid}", "contents", "labels", "milestones", "milestones/{number}"]) | |
| 130 | expect(doc.paths[`${R}/${path}`]?.get, path).toBeDefined(); | |
| 131 | const contents = doc.paths[`${R}/contents`].get.parameters.map((p: any) => p.name); | |
| 132 | expect(contents).toEqual(expect.arrayContaining(["path", "ref"])); | |
| 133 | const commits = doc.paths[`${R}/commits`].get.parameters.map((p: any) => p.name); | |
| 134 | expect(commits).toEqual(expect.arrayContaining(["ref", "limit"])); | |
| 135 | }); | |
| 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}"; |
new above
offline