BlueGit

timfa bluegit

Files

bluegit / internal / server / api_openapi.go

api_openapi.go

feat: beschrijf de API-objecten en geef ze een web_url
timfa project_87923614_bot_3aff574f6f98414b945a8799374f9092 · pushed by timfa · 3 weeks ago
Passed 2f39b617 History
api_openapi.go 13.3 KiB Download Raw
1package server
2
3import "strings"
4
5// decorateAPI vult request- en response-schema's in voor de kernobjecten.
6func decorateAPI(paths map[string]map[string]any, schemas map[string]any) {
7 for name, schema := range apiSchemas() {
8 schemas[name] = schema
9 }
10 for _, b := range apiBinds() {
11 op := apiOp(paths, b.path, b.method)
12 if op == nil {
13 continue
14 }
15 if b.body != "" {
16 op["requestBody"] = map[string]any{
17 "required": true,
18 "content": jsonSchema(schemaRef(b.body)),
19 }
20 }
21 responses, _ := op["responses"].(map[string]any)
22 if responses == nil {
23 responses = map[string]any{}
24 op["responses"] = responses
25 }
26 if b.empty {
27 responses[b.code] = map[string]any{"description": "No content"}
28 delete(responses, "200")
29 continue
30 }
31 schema := schemaRef(b.resp)
32 if b.array {
33 schema = map[string]any{"type": "array", "items": schema}
34 }
35 responses[b.code] = map[string]any{
36 "description": "OK",
37 "content": jsonSchema(schema),
38 }
39 }
40 if op := apiOp(paths, "/repos/{owner}/{repo}/issues/{number}/notes", "POST"); op != nil {
41 responses, _ := op["responses"].(map[string]any)
42 if responses == nil {
43 return
44 }
45 responses["200"] = map[string]any{
46 "description": "Issue, when the note contains only quick actions.",
47 "content": jsonSchema(schemaRef("Issue")),
48 }
49 }
50}
51
52func apiOp(paths map[string]map[string]any, path, method string) map[string]any {
53 item := paths[path]
54 if item == nil {
55 return nil
56 }
57 op, _ := item[strings.ToLower(method)].(map[string]any)
58 return op
59}
60
61func schemaRef(name string) map[string]any {
62 return map[string]any{"$ref": "#/components/schemas/" + name}
63}
64
65func jsonSchema(schema map[string]any) map[string]any {
66 return map[string]any{"application/json": map[string]any{"schema": schema}}
67}
68
69type apiBind struct {
70 path, method, body, resp, code string
71 array, empty bool
72}
73
74func apiBinds() []apiBind {
75 const (
76 mrs = "/projects/{owner}/{repo}/merge_requests"
77 mr = mrs + "/{number}"
78 pipes = "/projects/{owner}/{repo}/pipelines"
79 pipe = pipes + "/{id}"
80 job = pipe + "/jobs/{job}"
81 issues = "/repos/{owner}/{repo}/issues"
82 issue = issues + "/{number}"
83 branches = "/projects/{owner}/{repo}/repository/branches"
84 branch = branches + "/{branch}"
85 )
86 return []apiBind{
87 {path: mrs, method: "GET", code: "200", resp: "MergeRequest", array: true},
88 {path: mrs, method: "POST", code: "201", body: "MergeRequestCreate", resp: "MergeRequest"},
89 {path: mr, method: "GET", code: "200", resp: "MergeRequest"},
90 {path: mr, method: "PUT", code: "200", body: "MergeRequestUpdate", resp: "MergeRequest"},
91 {path: mr + "/merge", method: "POST", code: "200", body: "MergeRequestMerge", resp: "MergeResult"},
92 {path: mr + "/close", method: "POST", code: "200", resp: "MergeState"},
93 {path: mr + "/reopen", method: "POST", code: "200", resp: "MergeState"},
94
95 {path: issues, method: "GET", code: "200", resp: "IssueList"},
96 {path: issues, method: "POST", code: "201", body: "IssueWrite", resp: "Issue"},
97 {path: issue, method: "GET", code: "200", resp: "Issue"},
98 {path: issue, method: "PUT", code: "200", body: "IssueWrite", resp: "Issue"},
99 {path: issue, method: "DELETE", code: "204", empty: true},
100 {path: issue + "/notes", method: "POST", code: "201", body: "IssueNoteCreate", resp: "IssueNote"},
101
102 {path: pipes, method: "GET", code: "200", resp: "Pipeline", array: true},
103 {path: pipes, method: "POST", code: "201", body: "PipelineCreate", resp: "Pipeline"},
104 {path: pipe, method: "GET", code: "200", resp: "Pipeline"},
105 {path: pipe + "/cancel", method: "POST", code: "200", resp: "Pipeline"},
106 {path: pipe + "/jobs", method: "GET", code: "200", resp: "Job", array: true},
107 {path: job, method: "GET", code: "200", resp: "Job"},
108 {path: job + "/play", method: "POST", code: "200", resp: "Job"},
109 {path: job + "/retry", method: "POST", code: "200", resp: "Job"},
110 {path: job + "/cancel", method: "POST", code: "200", resp: "Job"},
111
112 {path: branches, method: "GET", code: "200", resp: "Branch", array: true},
113 {path: branches, method: "POST", code: "201", body: "BranchCreate", resp: "Branch"},
114 {path: branch, method: "PUT", code: "200", body: "BranchUpdate", resp: "Branch"},
115 {path: branch, method: "DELETE", code: "204", body: "BranchDelete", empty: true},
116
117 {path: "/groups/{path}/webhooks", method: "GET", code: "200", resp: "Webhook", array: true},
118 {path: "/groups/{path}/webhooks", method: "POST", code: "201", body: "WebhookCreate", resp: "Webhook"},
119 {path: "/projects/{owner}/{repo}/webhooks", method: "GET", code: "200", resp: "Webhook", array: true},
120 {path: "/projects/{owner}/{repo}/webhooks", method: "POST", code: "201", body: "WebhookCreate", resp: "Webhook"},
121 }
122}
123
124func apiSchemas() map[string]any {
125 when := str("RFC3339 timestamp. Null when the moment has not happened yet.")
126 return map[string]any{
127 "MergeRequest": obj("Merge request.", map[string]any{
128 "id": integer("Internal id."),
129 "iid": integer("Merge request number in the project."),
130 "title": str("Title."),
131 "description": str("Description."),
132 "source_branch": str("Source branch."),
133 "target_branch": str("Target branch."),
134 "author": str("Author username."),
135 "state": str("open, closed or merged."),
136 "draft": boolean("Draft merge request."),
137 "labels": str("Comma-separated label names."),
138 "remove_source_branch": boolean("Delete the source branch after a successful merge."),
139 "squash": boolean("Squash commits when merging."),
140 "squash_commit_message": str("Commit message used when squash is enabled. Empty uses the title."),
141 "web_url": str("Full page URL. An empty base URL yields a path."),
142 "created_at": when,
143 "updated_at": when,
144 }),
145 "MergeRequestCreate": obj("Fields for a new merge request. Omitted remove_source_branch means true. Omitted squash means false.", map[string]any{
146 "title": str("Title."),
147 "description": str("Description."),
148 "source_branch": str("Source branch."),
149 "target_branch": str("Target branch."),
150 "draft": boolean("Create as draft."),
151 "remove_source_branch": boolean("Delete the source branch after merge. Omitted means true."),
152 "squash": boolean("Squash commits. Omitted means false."),
153 "squash_commit_message": str("Squash commit message. Empty uses the merge request title."),
154 }),
155 "MergeRequestUpdate": obj("Fields to change on a merge request. Omitted merge options keep the stored value.", map[string]any{
156 "title": str("Title."),
157 "description": str("Description."),
158 "labels": str("Comma-separated label names."),
159 "remove_source_branch": boolean("Delete the source branch after merge."),
160 "squash": boolean("Squash commits."),
161 "squash_commit_message": str("Squash commit message."),
162 }),
163 "MergeRequestMerge": obj("Merge options for this attempt. Omitted fields keep the stored value.", map[string]any{
164 "remove_source_branch": boolean("Delete the source branch after merge."),
165 "squash": boolean("Squash commits."),
166 "squash_commit_message": str("Squash commit message."),
167 }),
168 "MergeResult": obj("Result of a merge.", map[string]any{
169 "state": str("merged."),
170 "source_branch_removed": boolean("True when the source branch was deleted."),
171 "source_branch_skip": str("Empty when the branch was removed. Otherwise disabled, protected, default, forbidden, missing or error."),
172 "web_url": str("Full page URL of the merge request."),
173 }),
174 "MergeState": obj("State after close or reopen.", map[string]any{
175 "state": str("open or closed."),
176 "web_url": str("Full page URL of the merge request."),
177 }),
178 "Issue": obj("Issue. The list omits notes.", map[string]any{
179 "id": integer("Issue number in the project."),
180 "title": str("Title."),
181 "description": str("Description."),
182 "status": str("open or closed."),
183 "confidential": boolean("Hidden from users who cannot triage."),
184 "author": str("Author username."),
185 "assignees": strArr("Assignee usernames."),
186 "labels": strArr("Label names."),
187 "milestone": str("Milestone title."),
188 "due_date": str("Due date, YYYY-MM-DD, or empty."),
189 "created_at": when,
190 "updated_at": when,
191 "closed_at": when,
192 "web_url": str("Full page URL. An empty base URL yields a path."),
193 "notes": map[string]any{"type": "array", "items": schemaRef("IssueNote"), "description": "Notes. Omitted on the list."},
194 }),
195 "IssueNote": obj("Issue note.", map[string]any{
196 "id": integer("Note id."),
197 "author": str("Author username."),
198 "body": str("Note text."),
199 "created_at": when,
200 }),
201 "IssueList": obj("Issue list.", map[string]any{
202 "issues": map[string]any{"type": "array", "items": schemaRef("Issue")},
203 }),
204 "IssueWrite": obj("Fields to create or update an issue. Omitted fields stay unchanged on update.", map[string]any{
205 "title": str("Title. Required when creating."),
206 "description": str("Description."),
207 "state": str("open or closed."),
208 "confidential": boolean("Confidential issue."),
209 "labels": strArr("Label names."),
210 "assignees": strArr("Assignee usernames."),
211 "milestone": str("Milestone title."),
212 "due_date": str("Due date, YYYY-MM-DD, or empty."),
213 }),
214 "IssueNoteCreate": obj("New issue note. A body that is only quick actions returns the issue instead of a note.", map[string]any{
215 "body": str("Note text, including optional quick actions."),
216 }),
217 "Pipeline": obj("Pipeline.", map[string]any{
218 "id": integer("Pipeline id."),
219 "sha": str("Commit SHA."),
220 "ref": str("Git ref, for example refs/heads/master."),
221 "status": str("Pipeline status."),
222 "source": str("Trigger source."),
223 "actor": str("Username that started the pipeline."),
224 "created_at": when,
225 "started_at": when,
226 "finished_at": when,
227 "web_url": str("Full page URL. An empty base URL yields a path."),
228 }),
229 "PipelineCreate": obj("Start a pipeline.", map[string]any{
230 "ref": str("Branch, tag or full ref to run."),
231 }),
232 "Job": obj("CI job.", map[string]any{
233 "id": integer("Job id."),
234 "name": str("Job name."),
235 "stage": str("Stage name."),
236 "status": str("Job status."),
237 "when": str("When the job runs."),
238 "allow_failure": boolean("A failed job does not fail the pipeline."),
239 "started_at": when,
240 "finished_at": when,
241 }),
242 "Branch": obj("Branch tip. Create and rename responses only include name.", map[string]any{
243 "name": str("Branch name."),
244 "commit": str("Tip commit SHA."),
245 "subject": str("Tip commit subject."),
246 "date": str("Tip commit date."),
247 "default": boolean("True for the default branch."),
248 }),
249 "BranchCreate": obj("Create a branch.", map[string]any{
250 "name": str("New branch name."),
251 "from": str("Existing branch or commit to start from."),
252 }),
253 "BranchUpdate": obj("Rename a branch.", map[string]any{
254 "name": str("New branch name."),
255 "confirm": str("Current branch name, repeated as confirmation."),
256 }),
257 "BranchDelete": obj("Delete a branch.", map[string]any{
258 "confirm": str("Branch name, repeated as confirmation."),
259 }),
260 "Webhook": obj("Webhook.", map[string]any{
261 "id": integer("Webhook id."),
262 "name": str("Display name."),
263 "preset": str("Preset name, or empty for a custom hook."),
264 "url": str("URL template."),
265 "method": str("HTTP method."),
266 "events": strArr("Events that trigger the hook."),
267 "branch_filter": str("Branch filter. Empty matches every branch."),
268 "active": boolean("Hook is enabled."),
269 }),
270 "WebhookCreate": obj("Create a webhook. Preset fields depend on the chosen preset.", map[string]any{
271 "name": str("Display name."),
272 "preset": str("Preset name."),
273 "branch_filter": str("Branch filter."),
274 "events": strArr("Events."),
275 "url": str("URL template."),
276 "username": str("Username for the preset."),
277 "avatar": str("Avatar URL."),
278 "icon": str("Icon URL or emoji."),
279 "alias": str("Alias."),
280 "token": str("Token. Stored as a secret and not returned."),
281 "chat": str("Chat id."),
282 "server": str("Server URL."),
283 "topic": str("Topic."),
284 "homeserver": str("Matrix homeserver."),
285 "room": str("Matrix room."),
286 "method": str("HTTP method."),
287 "content_type": str("Content type."),
288 "headers": str("Extra headers."),
289 "body": str("Body template."),
290 }),
291 }
292}
293
294func obj(desc string, props map[string]any) map[string]any {
295 return map[string]any{"type": "object", "description": desc, "properties": props}
296}
297
298func str(desc string) map[string]any {
299 return map[string]any{"type": "string", "description": desc}
300}
301
302func strArr(desc string) map[string]any {
303 return map[string]any{"type": "array", "description": desc, "items": map[string]any{"type": "string"}}
304}
305
306func boolean(desc string) map[string]any {
307 return map[string]any{"type": "boolean", "description": desc}
308}
309
310func integer(desc string) map[string]any {
311 return map[string]any{"type": "integer", "format": "int64", "description": desc}
312}