BlueGit

timfa bluegit

Files

bluegit / internal / server / api_openapi.go

api_openapi.go

api_openapi.go 23.2 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, "/projects/{owner}/{repo}/pipelines/{id}/retry", "POST"); op != nil {
41 responses, _ := op["responses"].(map[string]any)
42 if responses != nil {
43 if okResp, ok := responses["200"]; ok {
44 responses["201"] = okResp
45 }
46 }
47 }
48 if op := apiOp(paths, "/repos/{owner}/{repo}/issues/{number}/notes", "POST"); op != nil {
49 responses, _ := op["responses"].(map[string]any)
50 if responses == nil {
51 return
52 }
53 responses["200"] = map[string]any{
54 "description": "Issue, when the note contains only quick actions.",
55 "content": jsonSchema(schemaRef("Issue")),
56 }
57 }
58}
59
60func apiOp(paths map[string]map[string]any, path, method string) map[string]any {
61 item := paths[path]
62 if item == nil {
63 return nil
64 }
65 op, _ := item[strings.ToLower(method)].(map[string]any)
66 return op
67}
68
69func schemaRef(name string) map[string]any {
70 return map[string]any{"$ref": "#/components/schemas/" + name}
71}
72
73func jsonSchema(schema map[string]any) map[string]any {
74 return map[string]any{"application/json": map[string]any{"schema": schema}}
75}
76
77type apiBind struct {
78 path, method, body, resp, code string
79 array, empty bool
80}
81
82func apiBinds() []apiBind {
83 const (
84 mrs = "/projects/{owner}/{repo}/merge_requests"
85 mr = mrs + "/{number}"
86 pipes = "/projects/{owner}/{repo}/pipelines"
87 pipe = pipes + "/{id}"
88 job = pipe + "/jobs/{job}"
89 issues = "/repos/{owner}/{repo}/issues"
90 issue = issues + "/{number}"
91 branches = "/projects/{owner}/{repo}/repository/branches"
92 branch = branches + "/{branch}"
93 )
94 return []apiBind{
95 {path: "/user", method: "GET", code: "200", resp: "User"},
96 {path: "/user", method: "PUT", code: "200", body: "UserUpdate", resp: "User"},
97 {path: "/users/{username}", method: "GET", code: "200", resp: "User"},
98
99 {path: mrs, method: "GET", code: "200", resp: "MergeRequest", array: true},
100 {path: mrs, method: "POST", code: "201", body: "MergeRequestCreate", resp: "MergeRequest"},
101 {path: mr, method: "GET", code: "200", resp: "MergeRequest"},
102 {path: mr, method: "PUT", code: "200", body: "MergeRequestUpdate", resp: "MergeRequest"},
103 {path: mr + "/merge", method: "POST", code: "200", body: "MergeRequestMerge", resp: "MergeResult"},
104 {path: mr + "/close", method: "POST", code: "200", resp: "MergeState"},
105 {path: mr + "/reopen", method: "POST", code: "200", resp: "MergeState"},
106
107 {path: issues, method: "GET", code: "200", resp: "IssueList"},
108 {path: issues, method: "POST", code: "201", body: "IssueWrite", resp: "Issue"},
109 {path: issue, method: "GET", code: "200", resp: "Issue"},
110 {path: issue, method: "PUT", code: "200", body: "IssueWrite", resp: "Issue"},
111 {path: issue, method: "DELETE", code: "204", empty: true},
112 {path: issue + "/notes", method: "POST", code: "201", body: "IssueNoteCreate", resp: "IssueNote"},
113
114 {path: pipes, method: "GET", code: "200", resp: "Pipeline", array: true},
115 {path: pipes, method: "POST", code: "201", body: "PipelineCreate", resp: "Pipeline"},
116 {path: pipe, method: "GET", code: "200", resp: "Pipeline"},
117 {path: pipe + "/cancel", method: "POST", code: "200", resp: "Pipeline"},
118 {path: pipe + "/retry", method: "POST", code: "200", body: "PipelineRetry", resp: "Pipeline"},
119 {path: pipe + "/jobs", method: "GET", code: "200", resp: "Job", array: true},
120 {path: job, method: "GET", code: "200", resp: "Job"},
121 {path: job + "/play", method: "POST", code: "200", resp: "Job"},
122 {path: job + "/retry", method: "POST", code: "200", resp: "Job"},
123 {path: job + "/cancel", method: "POST", code: "200", resp: "Job"},
124
125 {path: branches, method: "GET", code: "200", resp: "Branch", array: true},
126 {path: branches, method: "POST", code: "201", body: "BranchCreate", resp: "Branch"},
127 {path: branch, method: "PUT", code: "200", body: "BranchUpdate", resp: "Branch"},
128 {path: branch, method: "DELETE", code: "204", body: "BranchDelete", empty: true},
129
130 {path: "/groups/{path}/webhooks", method: "GET", code: "200", resp: "Webhook", array: true},
131 {path: "/groups/{path}/webhooks", method: "POST", code: "201", body: "WebhookCreate", resp: "Webhook"},
132 {path: "/projects/{owner}/{repo}/webhooks", method: "GET", code: "200", resp: "Webhook", array: true},
133 {path: "/projects/{owner}/{repo}/webhooks", method: "POST", code: "201", body: "WebhookCreate", resp: "Webhook"},
134 {path: "/projects/{owner}/{repo}/secrets", method: "GET", code: "200", resp: "Secret", array: true},
135 {path: "/projects/{owner}/{repo}/secrets", method: "POST", code: "200", body: "SecretWrite", resp: "SecretName"},
136 {path: "/groups/{path}/secrets", method: "GET", code: "200", resp: "Secret", array: true},
137 {path: "/groups/{path}/secrets", method: "POST", code: "200", body: "SecretWrite", resp: "SecretName"},
138 {path: "/projects/{owner}/{repo}/secrets/inherited", method: "GET", code: "200", resp: "InheritedSecret", array: true},
139 {path: "/groups/{path}/webhooks/{id}", method: "PATCH", code: "200", body: "WebhookUpdate", resp: "Webhook"},
140 {path: "/groups/{path}/webhooks/{id}", method: "DELETE", code: "204", empty: true},
141 {path: "/groups/{path}/webhooks/{id}/copy", method: "POST", code: "201", body: "WebhookCopy", resp: "WebhookCopyResult"},
142 {path: "/projects/{owner}/{repo}/webhooks/{id}", method: "PATCH", code: "200", body: "WebhookUpdate", resp: "Webhook"},
143 {path: "/projects/{owner}/{repo}/webhooks/{id}", method: "DELETE", code: "204", empty: true},
144 {path: "/projects/{owner}/{repo}/webhooks/{id}/copy", method: "POST", code: "201", body: "WebhookCopy", resp: "WebhookCopyResult"},
145 }
146}
147
148func apiSchemas() map[string]any {
149 when := str("RFC3339 timestamp. Null when the moment has not happened yet.")
150 return map[string]any{
151 "MergeRequest": obj("Merge request.", map[string]any{
152 "id": integer("Internal id."),
153 "iid": integer("Merge request number in the project."),
154 "title": str("Title."),
155 "description": str("Description."),
156 "source_branch": str("Source branch."),
157 "target_branch": str("Target branch."),
158 "author": str("Author username."),
159 "state": str("open, closed or merged."),
160 "draft": boolean("Draft merge request."),
161 "labels": str("Comma-separated label names."),
162 "remove_source_branch": boolean("Delete the source branch after a successful merge."),
163 "squash": boolean("Squash commits when merging."),
164 "squash_commit_message": str("Commit message used when squash is enabled. Empty uses the title."),
165 "web_url": str("Full page URL. An empty base URL yields a path."),
166 "created_at": when,
167 "updated_at": when,
168 }),
169 "MergeRequestCreate": obj("Fields for a new merge request. Omitted remove_source_branch means true. Omitted squash means false.", map[string]any{
170 "title": str("Title."),
171 "description": str("Description."),
172 "source_branch": str("Source branch."),
173 "target_branch": str("Target branch."),
174 "draft": boolean("Create as draft."),
175 "remove_source_branch": boolean("Delete the source branch after merge. Omitted means true."),
176 "squash": boolean("Squash commits. Omitted means false."),
177 "squash_commit_message": str("Squash commit message. Empty uses the merge request title."),
178 }),
179 "MergeRequestUpdate": obj("Fields to change on a merge request. Omitted merge options keep the stored value.", map[string]any{
180 "title": str("Title."),
181 "description": str("Description."),
182 "labels": str("Comma-separated label names."),
183 "remove_source_branch": boolean("Delete the source branch after merge."),
184 "squash": boolean("Squash commits."),
185 "squash_commit_message": str("Squash commit message."),
186 }),
187 "MergeRequestMerge": obj("Merge options for this attempt. Omitted fields keep the stored value.", map[string]any{
188 "remove_source_branch": boolean("Delete the source branch after merge."),
189 "squash": boolean("Squash commits."),
190 "squash_commit_message": str("Squash commit message."),
191 }),
192 "MergeResult": obj("Result of a merge.", map[string]any{
193 "state": str("merged."),
194 "source_branch_removed": boolean("True when the source branch was deleted."),
195 "source_branch_skip": str("Empty when the branch was removed. Otherwise disabled, protected, default, forbidden, missing or error."),
196 "web_url": str("Full page URL of the merge request."),
197 }),
198 "MergeState": obj("State after close or reopen.", map[string]any{
199 "state": str("open or closed."),
200 "web_url": str("Full page URL of the merge request."),
201 }),
202 "Issue": obj("Issue. The list omits notes.", map[string]any{
203 "id": integer("Issue number in the project."),
204 "title": str("Title."),
205 "description": str("Description."),
206 "status": str("open or closed."),
207 "confidential": boolean("Hidden from users who cannot triage."),
208 "author": str("Author username."),
209 "assignees": strArr("Assignee usernames."),
210 "labels": strArr("Label names."),
211 "milestone": str("Milestone title."),
212 "due_date": str("Due date, YYYY-MM-DD, or empty."),
213 "created_at": when,
214 "updated_at": when,
215 "closed_at": when,
216 "web_url": str("Full page URL. An empty base URL yields a path."),
217 "notes": map[string]any{"type": "array", "items": schemaRef("IssueNote"), "description": "Notes. Omitted on the list."},
218 }),
219 "IssueNote": obj("Issue note.", map[string]any{
220 "id": integer("Note id."),
221 "author": str("Author username."),
222 "body": str("Note text."),
223 "created_at": when,
224 }),
225 "IssueList": obj("Issue list.", map[string]any{
226 "issues": map[string]any{"type": "array", "items": schemaRef("Issue")},
227 }),
228 "IssueWrite": obj("Fields to create or update an issue. Omitted fields stay unchanged on update.", map[string]any{
229 "title": str("Title. Required when creating."),
230 "description": str("Description."),
231 "state": str("open or closed."),
232 "confidential": boolean("Confidential issue."),
233 "labels": strArr("Label names."),
234 "assignees": strArr("Assignee usernames."),
235 "milestone": str("Milestone title."),
236 "due_date": str("Due date, YYYY-MM-DD, or empty."),
237 }),
238 "IssueNoteCreate": obj("New issue note. A body that is only quick actions returns the issue instead of a note.", map[string]any{
239 "body": str("Note text, including optional quick actions."),
240 }),
241 "Pipeline": obj("Pipeline.", map[string]any{
242 "id": integer("Pipeline id."),
243 "sha": str("Commit SHA."),
244 "ref": str("Git ref, for example refs/heads/master."),
245 "status": str("Pipeline status: queued, running, success, failed, canceled, waiting_for_update, waiting_for_job or manual. manual means only manual jobs are left, plus jobs that wait on them; such a pipeline is not running and has no finished_at until a manual job is played. A pipeline stopped by a newer pipeline stays canceled; see cancel_reason."),
246 "display_status": str("Status as the UI shows it: obsolete when every canceled job was superseded by a newer pipeline on the same ref, otherwise equal to status. Only in list and get responses."),
247 "cancel_reason": str("For status canceled: superseded (a newer pipeline started for the same ref) or manual. Null otherwise. Only in list and get responses."),
248 "waiting_for": map[string]any{"type": "object", "nullable": true, "description": "For status waiting_for_job: the running doNotInterrupt job (job_id, job_name, pipeline_id) in an older pipeline on the same ref that this pipeline waits for. Only in list and get responses."},
249 "source": str("Trigger source."),
250 "actor": str("Username that started the pipeline."),
251 "created_at": when,
252 "started_at": when,
253 "finished_at": when,
254 "web_url": str("Full page URL. An empty base URL yields a path."),
255 }),
256 "PipelineCreate": obj("Start a pipeline.", map[string]any{
257 "ref": str("Branch, tag or full ref to run."),
258 }),
259 "PipelineRetry": obj("Retry a pipeline. all starts a new pipeline on the same commit, ref, source and merge request. failed requeues failed jobs and the skipped or never-started jobs that depend on them. The response is 201 for all and 200 for failed.", map[string]any{
260 "mode": map[string]any{
261 "type": "string",
262 "description": "all or failed.",
263 "enum": []any{"all", "failed"},
264 },
265 }),
266 "Job": obj("CI job.", map[string]any{
267 "id": integer("Job id."),
268 "name": str("Job name."),
269 "stage": str("Stage name."),
270 "status": str("Job status."),
271 "when": str("When the job runs."),
272 "display_status": str("Status as the UI shows it: obsolete for a job canceled because a newer pipeline started for the same ref, otherwise equal to status."),
273 "cancel_reason": str("For status canceled: superseded or manual. Null otherwise."),
274 "do_not_interrupt": boolean("doNotInterrupt is set: the job is never stopped automatically, and cancelling it while it runs needs force=true."),
275 "failure_reason": str("For status failed: job_execution_timeout, script_failure or runner_system_failure when known. Null otherwise."),
276 "allow_failure": boolean("A failed job does not fail the pipeline."),
277 "started_at": when,
278 "finished_at": when,
279 }),
280 "Branch": obj("Branch tip. Create and rename responses only include name.", map[string]any{
281 "name": str("Branch name."),
282 "commit": str("Tip commit SHA."),
283 "subject": str("Tip commit subject."),
284 "date": str("Tip commit date."),
285 "default": boolean("True for the default branch."),
286 }),
287 "BranchCreate": obj("Create a branch.", map[string]any{
288 "name": str("New branch name."),
289 "from": str("Existing branch or commit to start from."),
290 }),
291 "BranchUpdate": obj("Rename a branch.", map[string]any{
292 "name": str("New branch name."),
293 "confirm": str("Current branch name, repeated as confirmation."),
294 }),
295 "BranchDelete": obj("Delete a branch.", map[string]any{
296 "confirm": str("Branch name, repeated as confirmation."),
297 }),
298 "Webhook": obj("Webhook.", map[string]any{
299 "id": integer("Webhook id."),
300 "name": str("Display name."),
301 "preset": str("Preset name, or empty for a custom hook."),
302 "url": str("URL template."),
303 "method": str("HTTP method."),
304 "events": strArr("Events that trigger the hook: push, merge_request, pipeline_success, pipeline_failure, release_published, issue, issue_opened, issue_closed, issue_reopened, issue_updated, issue_comment, merge_request_comment. issue and merge_request also cover the finer issue_* and merge_request_comment events."),
305 "branch_filter": str("Branch filter. Empty matches every branch."),
306 "active": boolean("Hook is enabled."),
307 }),
308 "User": obj("User. counts, repos and groups are present on GET /users/{username}, which is public. Without a token only public repositories and groups are included, and contributions count only those repositories. instance_admin and language are present for the signed-in user.", map[string]any{
309 "id": integer("User id."),
310 "username": str("Username."),
311 "name": str("Display name. Empty when unset."),
312 "bio": str("Profile text. Empty when unset."),
313 "avatar_url": str("Avatar URL."),
314 "created_at": when,
315 "web_url": str("Profile page at /users/{username}."),
316 "instance_admin": boolean("Instance administrator. Only on the signed-in user."),
317 "language": str("Interface language. Only on the signed-in user."),
318 "counts": obj("Totals the viewer is allowed to see.", map[string]any{
319 "repos": integer("Owned repositories visible to the viewer."),
320 "groups": integer("Groups the user belongs to that the viewer may see."),
321 "contributions": integer("Contributions in the last 12 months in repositories the viewer may see."),
322 }),
323 "repos": map[string]any{"type": "array", "description": "Owned repositories visible to the viewer.", "items": schemaRef("UserRepo")},
324 "groups": map[string]any{"type": "array", "description": "Groups visible to the viewer.", "items": schemaRef("UserGroup")},
325 }),
326 "UserUpdate": obj("Fields to change on the signed-in user. Omitted fields stay unchanged.", map[string]any{
327 "name": str("Display name. Empty clears it."),
328 "bio": str("Profile text. Empty clears it. Newlines are kept."),
329 "language": str("Interface language."),
330 }),
331 "UserRepo": obj("Repository on a user profile.", map[string]any{
332 "id": integer("Repository id."),
333 "name": str("Repository name."),
334 "path": str("Full path, owner/name."),
335 "description": str("Description."),
336 "visibility": str("public or private."),
337 "web_url": str("Full page URL."),
338 }),
339 "UserGroup": obj("Group on a user profile.", map[string]any{
340 "id": integer("Group id."),
341 "name": str("Group name."),
342 "path": str("Group path."),
343 "description": str("Description."),
344 "visibility": str("public or private."),
345 "web_url": str("Full page URL."),
346 }),
347 "WebhookCreate": obj("Create a webhook. Preset fields depend on the chosen preset.", map[string]any{
348 "name": str("Display name."),
349 "preset": str("Preset name."),
350 "branch_filter": str("Branch filter."),
351 "events": strArr("Events, see the list on the webhook schema."),
352 "url": str("URL template."),
353 "username": str("Username for the preset."),
354 "avatar": str("Avatar URL."),
355 "icon": str("Icon URL or emoji."),
356 "alias": str("Alias."),
357 "token": str("Name of the secret that holds the token. The value is never returned."),
358 "chat": str("Chat id."),
359 "server": str("Server URL."),
360 "topic": str("Topic."),
361 "homeserver": str("Matrix homeserver."),
362 "room": str("Matrix room."),
363 "method": str("HTTP method."),
364 "content_type": str("Content type."),
365 "headers": str("Extra headers."),
366 "body": str("Body template."),
367 }),
368 "WebhookUpdate": obj("Change a webhook. Omitted fields keep the stored value. An empty or omitted token keeps the stored secret reference; secret values are never returned.", map[string]any{
369 "name": str("Display name."),
370 "preset": str("Preset name."),
371 "branch_filter": str("Branch filter."),
372 "events": strArr("Events, see the list on the webhook schema."),
373 "active": boolean("Enable or disable the hook."),
374 "url": str("URL template."),
375 "username": str("Username for the preset."),
376 "avatar": str("Avatar URL."),
377 "icon": str("Icon URL or emoji."),
378 "alias": str("Alias."),
379 "token": str("Name of the secret that holds the token. Empty keeps the current one."),
380 "chat": str("Chat id."),
381 "server": str("Server URL."),
382 "topic": str("Topic."),
383 "homeserver": str("Matrix homeserver."),
384 "room": str("Matrix room."),
385 "method": str("HTTP method."),
386 "content_type": str("Content type."),
387 "headers": str("Extra headers. Empty keeps the current headers."),
388 "body": str("Body template."),
389 }),
390 "Secret": obj("A secret. Values are never returned.", map[string]any{
391 "name": str("Secret name."),
392 "protected": boolean("Only injected on protected refs."),
393 "expand": boolean("$NAME and ${NAME} in the value are expanded in the runner after group, project, job and CI_* variables are merged. $$ gives a literal $. Unknown names and cycles stay literal, like GitLab."),
394 "created_at": str("Creation time (RFC 3339)."),
395 }),
396 "SecretWrite": obj("Create or replace a secret.", map[string]any{
397 "name": str("Secret name."),
398 "value": str("Secret value. Never returned."),
399 "protected": boolean("Only injected on protected refs."),
400 "expand": boolean("Expand $NAME references in the value at job time. Default false; omitted on update keeps the stored setting."),
401 }),
402 "SecretName": obj("The stored secret name.", map[string]any{"name": str("Secret name.")}),
403 "InheritedSecret": obj("A group secret the project inherits. Values are never returned. Jobs get group secrets first; a project secret with the same name wins.", map[string]any{
404 "name": str("Secret name."),
405 "group": str("Path of the group it comes from."),
406 "protected": boolean("Only injected on protected refs."),
407 "overridden": boolean("A project secret with the same name replaces it."),
408 }),
409 "WebhookCopy": obj("Copy a webhook to a project or group where you are maintainer. Secrets the hook references and the target cannot already see are copied encrypted on the server; their values never reach the client.", map[string]any{
410 "target_type": str("project or group."),
411 "target": str("Target path: owner/project or group path."),
412 "name": str("Optional new name. Default keeps the name."),
413 "events": strArr("Optional event filter. Default keeps the events."),
414 }),
415 "WebhookCopyResult": obj("The new webhook plus the names (never values) of copied secrets.", map[string]any{
416 "id": integer("New webhook id."),
417 "name": str("Display name."),
418 "preset": str("Preset name."),
419 "url": str("URL template."),
420 "method": str("HTTP method."),
421 "events": strArr("Events."),
422 "branch_filter": str("Branch filter."),
423 "active": boolean("Hook is enabled."),
424 "scope": str("repo or group."),
425 "copied_secrets": strArr("Names of secrets copied to the target."),
426 "missing_secrets": strArr("Referenced secret names found nowhere; add them in the target."),
427 }),
428 }
429}
430
431func obj(desc string, props map[string]any) map[string]any {
432 return map[string]any{"type": "object", "description": desc, "properties": props}
433}
434
435func str(desc string) map[string]any {
436 return map[string]any{"type": "string", "description": desc}
437}
438
439func strArr(desc string) map[string]any {
440 return map[string]any{"type": "array", "description": desc, "items": map[string]any{"type": "string"}}
441}
442
443func boolean(desc string) map[string]any {
444 return map[string]any{"type": "boolean", "description": desc}
445}
446
447func integer(desc string) map[string]any {
448 return map[string]any{"type": "integer", "format": "int64", "description": desc}
449}