| 1 | package server |
| 2 | |
| 3 | import "strings" |
| 4 | |
| 5 | // decorateAPI vult request- en response-schema's in voor de kernobjecten. |
| 6 | func 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 | |
| 60 | func 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 | |
| 69 | func schemaRef(name string) map[string]any { |
| 70 | return map[string]any{"$ref": "#/components/schemas/" + name} |
| 71 | } |
| 72 | |
| 73 | func jsonSchema(schema map[string]any) map[string]any { |
| 74 | return map[string]any{"application/json": map[string]any{"schema": schema}} |
| 75 | } |
| 76 | |
| 77 | type apiBind struct { |
| 78 | path, method, body, resp, code string |
| 79 | array, empty bool |
| 80 | } |
| 81 | |
| 82 | func 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 | } |
| 135 | } |
| 136 | |
| 137 | func apiSchemas() map[string]any { |
| 138 | when := str("RFC3339 timestamp. Null when the moment has not happened yet.") |
| 139 | return map[string]any{ |
| 140 | "MergeRequest": obj("Merge request.", map[string]any{ |
| 141 | "id": integer("Internal id."), |
| 142 | "iid": integer("Merge request number in the project."), |
| 143 | "title": str("Title."), |
| 144 | "description": str("Description."), |
| 145 | "source_branch": str("Source branch."), |
| 146 | "target_branch": str("Target branch."), |
| 147 | "author": str("Author username."), |
| 148 | "state": str("open, closed or merged."), |
| 149 | "draft": boolean("Draft merge request."), |
| 150 | "labels": str("Comma-separated label names."), |
| 151 | "remove_source_branch": boolean("Delete the source branch after a successful merge."), |
| 152 | "squash": boolean("Squash commits when merging."), |
| 153 | "squash_commit_message": str("Commit message used when squash is enabled. Empty uses the title."), |
| 154 | "web_url": str("Full page URL. An empty base URL yields a path."), |
| 155 | "created_at": when, |
| 156 | "updated_at": when, |
| 157 | }), |
| 158 | "MergeRequestCreate": obj("Fields for a new merge request. Omitted remove_source_branch means true. Omitted squash means false.", map[string]any{ |
| 159 | "title": str("Title."), |
| 160 | "description": str("Description."), |
| 161 | "source_branch": str("Source branch."), |
| 162 | "target_branch": str("Target branch."), |
| 163 | "draft": boolean("Create as draft."), |
| 164 | "remove_source_branch": boolean("Delete the source branch after merge. Omitted means true."), |
| 165 | "squash": boolean("Squash commits. Omitted means false."), |
| 166 | "squash_commit_message": str("Squash commit message. Empty uses the merge request title."), |
| 167 | }), |
| 168 | "MergeRequestUpdate": obj("Fields to change on a merge request. Omitted merge options keep the stored value.", map[string]any{ |
| 169 | "title": str("Title."), |
| 170 | "description": str("Description."), |
| 171 | "labels": str("Comma-separated label names."), |
| 172 | "remove_source_branch": boolean("Delete the source branch after merge."), |
| 173 | "squash": boolean("Squash commits."), |
| 174 | "squash_commit_message": str("Squash commit message."), |
| 175 | }), |
| 176 | "MergeRequestMerge": obj("Merge options for this attempt. Omitted fields keep the stored value.", map[string]any{ |
| 177 | "remove_source_branch": boolean("Delete the source branch after merge."), |
| 178 | "squash": boolean("Squash commits."), |
| 179 | "squash_commit_message": str("Squash commit message."), |
| 180 | }), |
| 181 | "MergeResult": obj("Result of a merge.", map[string]any{ |
| 182 | "state": str("merged."), |
| 183 | "source_branch_removed": boolean("True when the source branch was deleted."), |
| 184 | "source_branch_skip": str("Empty when the branch was removed. Otherwise disabled, protected, default, forbidden, missing or error."), |
| 185 | "web_url": str("Full page URL of the merge request."), |
| 186 | }), |
| 187 | "MergeState": obj("State after close or reopen.", map[string]any{ |
| 188 | "state": str("open or closed."), |
| 189 | "web_url": str("Full page URL of the merge request."), |
| 190 | }), |
| 191 | "Issue": obj("Issue. The list omits notes.", map[string]any{ |
| 192 | "id": integer("Issue number in the project."), |
| 193 | "title": str("Title."), |
| 194 | "description": str("Description."), |
| 195 | "status": str("open or closed."), |
| 196 | "confidential": boolean("Hidden from users who cannot triage."), |
| 197 | "author": str("Author username."), |
| 198 | "assignees": strArr("Assignee usernames."), |
| 199 | "labels": strArr("Label names."), |
| 200 | "milestone": str("Milestone title."), |
| 201 | "due_date": str("Due date, YYYY-MM-DD, or empty."), |
| 202 | "created_at": when, |
| 203 | "updated_at": when, |
| 204 | "closed_at": when, |
| 205 | "web_url": str("Full page URL. An empty base URL yields a path."), |
| 206 | "notes": map[string]any{"type": "array", "items": schemaRef("IssueNote"), "description": "Notes. Omitted on the list."}, |
| 207 | }), |
| 208 | "IssueNote": obj("Issue note.", map[string]any{ |
| 209 | "id": integer("Note id."), |
| 210 | "author": str("Author username."), |
| 211 | "body": str("Note text."), |
| 212 | "created_at": when, |
| 213 | }), |
| 214 | "IssueList": obj("Issue list.", map[string]any{ |
| 215 | "issues": map[string]any{"type": "array", "items": schemaRef("Issue")}, |
| 216 | }), |
| 217 | "IssueWrite": obj("Fields to create or update an issue. Omitted fields stay unchanged on update.", map[string]any{ |
| 218 | "title": str("Title. Required when creating."), |
| 219 | "description": str("Description."), |
| 220 | "state": str("open or closed."), |
| 221 | "confidential": boolean("Confidential issue."), |
| 222 | "labels": strArr("Label names."), |
| 223 | "assignees": strArr("Assignee usernames."), |
| 224 | "milestone": str("Milestone title."), |
| 225 | "due_date": str("Due date, YYYY-MM-DD, or empty."), |
| 226 | }), |
| 227 | "IssueNoteCreate": obj("New issue note. A body that is only quick actions returns the issue instead of a note.", map[string]any{ |
| 228 | "body": str("Note text, including optional quick actions."), |
| 229 | }), |
| 230 | "Pipeline": obj("Pipeline.", map[string]any{ |
| 231 | "id": integer("Pipeline id."), |
| 232 | "sha": str("Commit SHA."), |
| 233 | "ref": str("Git ref, for example refs/heads/master."), |
| 234 | "status": str("Pipeline status. A pipeline stopped by a newer pipeline stays canceled; see cancel_reason."), |
| 235 | "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."), |
| 236 | "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."), |
| 237 | "source": str("Trigger source."), |
| 238 | "actor": str("Username that started the pipeline."), |
| 239 | "created_at": when, |
| 240 | "started_at": when, |
| 241 | "finished_at": when, |
| 242 | "web_url": str("Full page URL. An empty base URL yields a path."), |
| 243 | }), |
| 244 | "PipelineCreate": obj("Start a pipeline.", map[string]any{ |
| 245 | "ref": str("Branch, tag or full ref to run."), |
| 246 | }), |
| 247 | "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{ |
| 248 | "mode": map[string]any{ |
| 249 | "type": "string", |
| 250 | "description": "all or failed.", |
| 251 | "enum": []any{"all", "failed"}, |
| 252 | }, |
| 253 | }), |
| 254 | "Job": obj("CI job.", map[string]any{ |
| 255 | "id": integer("Job id."), |
| 256 | "name": str("Job name."), |
| 257 | "stage": str("Stage name."), |
| 258 | "status": str("Job status."), |
| 259 | "when": str("When the job runs."), |
| 260 | "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."), |
| 261 | "cancel_reason": str("For status canceled: superseded or manual. Null otherwise."), |
| 262 | "failure_reason": str("For status failed: job_execution_timeout, script_failure or runner_system_failure when known. Null otherwise."), |
| 263 | "allow_failure": boolean("A failed job does not fail the pipeline."), |
| 264 | "started_at": when, |
| 265 | "finished_at": when, |
| 266 | }), |
| 267 | "Branch": obj("Branch tip. Create and rename responses only include name.", map[string]any{ |
| 268 | "name": str("Branch name."), |
| 269 | "commit": str("Tip commit SHA."), |
| 270 | "subject": str("Tip commit subject."), |
| 271 | "date": str("Tip commit date."), |
| 272 | "default": boolean("True for the default branch."), |
| 273 | }), |
| 274 | "BranchCreate": obj("Create a branch.", map[string]any{ |
| 275 | "name": str("New branch name."), |
| 276 | "from": str("Existing branch or commit to start from."), |
| 277 | }), |
| 278 | "BranchUpdate": obj("Rename a branch.", map[string]any{ |
| 279 | "name": str("New branch name."), |
| 280 | "confirm": str("Current branch name, repeated as confirmation."), |
| 281 | }), |
| 282 | "BranchDelete": obj("Delete a branch.", map[string]any{ |
| 283 | "confirm": str("Branch name, repeated as confirmation."), |
| 284 | }), |
| 285 | "Webhook": obj("Webhook.", map[string]any{ |
| 286 | "id": integer("Webhook id."), |
| 287 | "name": str("Display name."), |
| 288 | "preset": str("Preset name, or empty for a custom hook."), |
| 289 | "url": str("URL template."), |
| 290 | "method": str("HTTP method."), |
| 291 | "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."), |
| 292 | "branch_filter": str("Branch filter. Empty matches every branch."), |
| 293 | "active": boolean("Hook is enabled."), |
| 294 | }), |
| 295 | "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{ |
| 296 | "id": integer("User id."), |
| 297 | "username": str("Username."), |
| 298 | "name": str("Display name. Empty when unset."), |
| 299 | "bio": str("Profile text. Empty when unset."), |
| 300 | "avatar_url": str("Avatar URL."), |
| 301 | "created_at": when, |
| 302 | "web_url": str("Profile page at /users/{username}."), |
| 303 | "instance_admin": boolean("Instance administrator. Only on the signed-in user."), |
| 304 | "language": str("Interface language. Only on the signed-in user."), |
| 305 | "counts": obj("Totals the viewer is allowed to see.", map[string]any{ |
| 306 | "repos": integer("Owned repositories visible to the viewer."), |
| 307 | "groups": integer("Groups the user belongs to that the viewer may see."), |
| 308 | "contributions": integer("Contributions in the last 12 months in repositories the viewer may see."), |
| 309 | }), |
| 310 | "repos": map[string]any{"type": "array", "description": "Owned repositories visible to the viewer.", "items": schemaRef("UserRepo")}, |
| 311 | "groups": map[string]any{"type": "array", "description": "Groups visible to the viewer.", "items": schemaRef("UserGroup")}, |
| 312 | }), |
| 313 | "UserUpdate": obj("Fields to change on the signed-in user. Omitted fields stay unchanged.", map[string]any{ |
| 314 | "name": str("Display name. Empty clears it."), |
| 315 | "bio": str("Profile text. Empty clears it. Newlines are kept."), |
| 316 | "language": str("Interface language."), |
| 317 | }), |
| 318 | "UserRepo": obj("Repository on a user profile.", map[string]any{ |
| 319 | "id": integer("Repository id."), |
| 320 | "name": str("Repository name."), |
| 321 | "path": str("Full path, owner/name."), |
| 322 | "description": str("Description."), |
| 323 | "visibility": str("public or private."), |
| 324 | "web_url": str("Full page URL."), |
| 325 | }), |
| 326 | "UserGroup": obj("Group on a user profile.", map[string]any{ |
| 327 | "id": integer("Group id."), |
| 328 | "name": str("Group name."), |
| 329 | "path": str("Group path."), |
| 330 | "description": str("Description."), |
| 331 | "visibility": str("public or private."), |
| 332 | "web_url": str("Full page URL."), |
| 333 | }), |
| 334 | "WebhookCreate": obj("Create a webhook. Preset fields depend on the chosen preset.", map[string]any{ |
| 335 | "name": str("Display name."), |
| 336 | "preset": str("Preset name."), |
| 337 | "branch_filter": str("Branch filter."), |
| 338 | "events": strArr("Events, see the list on the webhook schema."), |
| 339 | "url": str("URL template."), |
| 340 | "username": str("Username for the preset."), |
| 341 | "avatar": str("Avatar URL."), |
| 342 | "icon": str("Icon URL or emoji."), |
| 343 | "alias": str("Alias."), |
| 344 | "token": str("Token. Stored as a secret and not returned."), |
| 345 | "chat": str("Chat id."), |
| 346 | "server": str("Server URL."), |
| 347 | "topic": str("Topic."), |
| 348 | "homeserver": str("Matrix homeserver."), |
| 349 | "room": str("Matrix room."), |
| 350 | "method": str("HTTP method."), |
| 351 | "content_type": str("Content type."), |
| 352 | "headers": str("Extra headers."), |
| 353 | "body": str("Body template."), |
| 354 | }), |
| 355 | } |
| 356 | } |
| 357 | |
| 358 | func obj(desc string, props map[string]any) map[string]any { |
| 359 | return map[string]any{"type": "object", "description": desc, "properties": props} |
| 360 | } |
| 361 | |
| 362 | func str(desc string) map[string]any { |
| 363 | return map[string]any{"type": "string", "description": desc} |
| 364 | } |
| 365 | |
| 366 | func strArr(desc string) map[string]any { |
| 367 | return map[string]any{"type": "array", "description": desc, "items": map[string]any{"type": "string"}} |
| 368 | } |
| 369 | |
| 370 | func boolean(desc string) map[string]any { |
| 371 | return map[string]any{"type": "boolean", "description": desc} |
| 372 | } |
| 373 | |
| 374 | func integer(desc string) map[string]any { |
| 375 | return map[string]any{"type": "integer", "format": "int64", "description": desc} |
| 376 | } |