BlueGit

timfa bluegit

Files

bluegit / internal / server / api_openapi.go

api_openapi.go

api_openapi.go 32.4 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 content := jsonSchema(schemaRef(b.body))
17 if b.multipart {
18 content = map[string]any{
19 "multipart/form-data": map[string]any{"schema": schemaRef(b.body)},
20 }
21 }
22 op["requestBody"] = map[string]any{
23 "required": !b.optional,
24 "content": content,
25 }
26 }
27 if len(b.query) > 0 {
28 params, _ := op["parameters"].([]any)
29 for _, q := range b.query {
30 params = append(params, map[string]any{
31 "name": q.name,
32 "in": "query",
33 "required": q.required,
34 "description": q.desc,
35 "schema": map[string]any{"type": "string"},
36 })
37 }
38 op["parameters"] = params
39 }
40 if b.resp == "" && !b.empty {
41 continue
42 }
43 responses, _ := op["responses"].(map[string]any)
44 if responses == nil {
45 responses = map[string]any{}
46 op["responses"] = responses
47 }
48 if b.empty {
49 responses[b.code] = map[string]any{"description": "No content"}
50 delete(responses, "200")
51 continue
52 }
53 schema := schemaRef(b.resp)
54 if b.array {
55 schema = map[string]any{"type": "array", "items": schema}
56 }
57 responses[b.code] = map[string]any{
58 "description": "OK",
59 "content": jsonSchema(schema),
60 }
61 }
62 if op := apiOp(paths, "/projects/{owner}/{repo}/pipelines/{id}/retry", "POST"); op != nil {
63 responses, _ := op["responses"].(map[string]any)
64 if responses != nil {
65 if okResp, ok := responses["200"]; ok {
66 responses["201"] = okResp
67 }
68 }
69 }
70 if op := apiOp(paths, "/repos/{owner}/{repo}/issues/{number}/notes", "POST"); op != nil {
71 responses, _ := op["responses"].(map[string]any)
72 if responses == nil {
73 return
74 }
75 responses["200"] = map[string]any{
76 "description": "Issue, when the note contains only quick actions.",
77 "content": jsonSchema(schemaRef("Issue")),
78 }
79 }
80}
81
82func apiOp(paths map[string]map[string]any, path, method string) map[string]any {
83 item := paths[path]
84 if item == nil {
85 return nil
86 }
87 op, _ := item[strings.ToLower(method)].(map[string]any)
88 return op
89}
90
91func schemaRef(name string) map[string]any {
92 return map[string]any{"$ref": "#/components/schemas/" + name}
93}
94
95func jsonSchema(schema map[string]any) map[string]any {
96 return map[string]any{"application/json": map[string]any{"schema": schema}}
97}
98
99type apiBind struct {
100 path, method, body, resp, code string
101 array, empty, multipart bool
102 optional bool
103 query []apiQuery
104}
105
106type apiQuery struct {
107 name, desc string
108 required bool
109}
110
111func q(name, desc string, required bool) apiQuery {
112 return apiQuery{name: name, desc: desc, required: required}
113}
114
115func apiBinds() []apiBind {
116 const (
117 mrs = "/projects/{owner}/{repo}/merge_requests"
118 mr = mrs + "/{number}"
119 pipes = "/projects/{owner}/{repo}/pipelines"
120 pipe = pipes + "/{id}"
121 job = pipe + "/jobs/{job}"
122 issues = "/repos/{owner}/{repo}/issues"
123 issue = issues + "/{number}"
124 branches = "/projects/{owner}/{repo}/repository/branches"
125 branch = branches + "/{branch}"
126 )
127 return []apiBind{
128 {path: "/user", method: "GET", code: "200", resp: "User"},
129 {path: "/user", method: "PUT", code: "200", body: "UserUpdate", resp: "User"},
130 {path: "/users/{username}", method: "GET", code: "200", resp: "User"},
131
132 {path: mrs, method: "GET", code: "200", resp: "MergeRequest", array: true},
133 {path: mrs, method: "POST", code: "201", body: "MergeRequestCreate", resp: "MergeRequest"},
134 {path: mr, method: "GET", code: "200", resp: "MergeRequest"},
135 {path: mr, method: "PUT", code: "200", body: "MergeRequestUpdate", resp: "MergeRequest"},
136 {path: mr + "/merge", method: "POST", code: "200", body: "MergeRequestMerge", resp: "MergeResult"},
137 {path: mr + "/close", method: "POST", code: "200", resp: "MergeState"},
138 {path: mr + "/reopen", method: "POST", code: "200", resp: "MergeState"},
139
140 {path: issues, method: "GET", code: "200", resp: "IssueList"},
141 {path: issues, method: "POST", code: "201", body: "IssueWrite", resp: "Issue"},
142 {path: issue, method: "GET", code: "200", resp: "Issue"},
143 {path: issue, method: "PUT", code: "200", body: "IssueWrite", resp: "Issue"},
144 {path: issue, method: "DELETE", code: "204", empty: true},
145 {path: issue + "/notes", method: "POST", code: "201", body: "IssueNoteCreate", resp: "IssueNote"},
146
147 {path: pipes, method: "GET", code: "200", resp: "Pipeline", array: true},
148 {path: pipes, method: "POST", code: "201", body: "PipelineCreate", resp: "Pipeline"},
149 {path: pipe, method: "GET", code: "200", resp: "Pipeline"},
150 {path: pipe + "/cancel", method: "POST", code: "200", resp: "Pipeline"},
151 {path: pipe + "/retry", method: "POST", code: "200", body: "PipelineRetry", resp: "Pipeline", optional: true},
152 {path: pipe + "/jobs", method: "GET", code: "200", resp: "Job", array: true},
153 {path: job, method: "GET", code: "200", resp: "Job"},
154 {path: job + "/play", method: "POST", code: "200", resp: "Job"},
155 {path: job + "/retry", method: "POST", code: "200", resp: "Job"},
156 {path: job + "/cancel", method: "POST", code: "200", resp: "Job"},
157
158 {path: branches, method: "GET", code: "200", resp: "Branch", array: true},
159 {path: branches, method: "POST", code: "201", body: "BranchCreate", resp: "Branch"},
160 {path: branches, method: "PUT", code: "200", body: "BranchUpdate", resp: "Branch", optional: true, query: []apiQuery{
161 q("name", "Current branch name. Preferred when the name contains a slash and the ingress rejects %2F.", true),
162 }},
163 {path: branches, method: "DELETE", code: "204", body: "BranchDelete", empty: true, optional: true, query: []apiQuery{
164 q("name", "Branch to delete. May also be sent in the JSON body. Use this when the name contains a slash and the ingress rejects %2F.", false),
165 }},
166 {path: branch, method: "PUT", code: "200", body: "BranchUpdate", resp: "Branch"},
167 {path: branch, method: "DELETE", code: "204", body: "BranchDelete", empty: true},
168
169 {path: "/groups/{path}", method: "DELETE", code: "204", body: "GroupDelete", empty: true},
170 {path: "/groups/{path}/webhooks", method: "GET", code: "200", resp: "Webhook", array: true},
171 {path: "/groups/{path}/webhooks", method: "POST", code: "201", body: "WebhookCreate", resp: "Webhook"},
172 {path: "/projects/{owner}/{repo}/webhooks", method: "GET", code: "200", resp: "Webhook", array: true},
173 {path: "/projects/{owner}/{repo}/webhooks", method: "POST", code: "201", body: "WebhookCreate", resp: "Webhook"},
174 {path: "/projects/{owner}/{repo}/secrets", method: "GET", code: "200", resp: "Secret", array: true},
175 {path: "/projects/{owner}/{repo}/secrets", method: "POST", code: "200", body: "SecretWrite", resp: "SecretName"},
176 {path: "/groups/{path}/secrets", method: "GET", code: "200", resp: "Secret", array: true},
177 {path: "/groups/{path}/secrets", method: "POST", code: "200", body: "SecretWrite", resp: "SecretName"},
178 {path: "/projects/{owner}/{repo}/fork", method: "POST", code: "201", body: "ForkCreate", resp: "ForkedProject"},
179 {path: "/projects/{owner}/{repo}/sync-upstream", method: "POST", code: "200", body: "SyncUpstream", resp: "SyncResult"},
180 {path: "/projects/{owner}/{repo}/upstream-merge-requests", method: "POST", code: "201", body: "ForkMergeRequest", resp: "ForkedProject"},
181 {path: "/projects/{owner}/{repo}/forks", method: "GET", code: "200", resp: "ForkedProject", array: true},
182 {path: "/projects/{owner}/{repo}/secrets/inherited", method: "GET", code: "200", resp: "InheritedSecret", array: true},
183 {path: "/groups/{path}/webhooks/{id}", method: "PATCH", code: "200", body: "WebhookUpdate", resp: "Webhook"},
184 {path: "/groups/{path}/webhooks/{id}", method: "DELETE", code: "204", empty: true},
185 {path: "/groups/{path}/webhooks/{id}/copy", method: "POST", code: "201", body: "WebhookCopy", resp: "WebhookCopyResult"},
186 {path: "/projects/{owner}/{repo}/webhooks/{id}", method: "PATCH", code: "200", body: "WebhookUpdate", resp: "Webhook"},
187 {path: "/projects/{owner}/{repo}/webhooks/{id}", method: "DELETE", code: "204", empty: true},
188 {path: "/projects/{owner}/{repo}/webhooks/{id}/copy", method: "POST", code: "201", body: "WebhookCopy", resp: "WebhookCopyResult"},
189
190 {path: "/projects", method: "POST", code: "201", body: "ProjectCreate", resp: "Project"},
191 {path: "/projects/{owner}/{repo}", method: "PUT", code: "200", body: "ProjectUpdate", resp: "Project"},
192 {path: "/projects/{owner}/{repo}/logo", method: "POST", code: "200", body: "LogoUpload", resp: "LogoResult", multipart: true},
193 {path: "/groups/{path}/logo", method: "POST", code: "200", body: "LogoUpload", resp: "LogoResult", multipart: true},
194 {path: "/projects/{owner}/{repo}/protected_branches", method: "POST", code: "201", body: "ProtectedPattern", resp: "ProtectedPattern"},
195 {path: "/projects/{owner}/{repo}/protected_branches", method: "DELETE", code: "204", body: "ProtectedPattern", empty: true, optional: true, query: []apiQuery{
196 q("pattern", "Pattern to unprotect. May also be sent in the JSON body. Use this when the pattern contains a slash and the ingress rejects %2F.", false),
197 }},
198 {path: "/projects/{owner}/{repo}/protected_tags", method: "POST", code: "201", body: "ProtectedPattern", resp: "ProtectedPattern"},
199 {path: "/projects/{owner}/{repo}/protected_tags", method: "DELETE", code: "204", body: "ProtectedPattern", empty: true, optional: true, query: []apiQuery{
200 q("pattern", "Pattern to unprotect. May also be sent in the JSON body. Use this when the pattern contains a slash and the ingress rejects %2F.", false),
201 }},
202 {path: "/projects/{owner}/{repo}/repository/files", method: "GET", query: []apiQuery{
203 q("path", "File path, including slashes. Preferred when the ingress rejects %2F in the URL path.", true),
204 q("ref", "Branch, tag or commit. Default: the project's default branch.", false),
205 }},
206 {path: "/projects/{owner}/{repo}/ci/lint", method: "POST", code: "200", body: "CILint", resp: "CILintResult"},
207 }
208}
209
210func apiSchemas() map[string]any {
211 when := str("RFC3339 timestamp. Null when the moment has not happened yet.")
212 return map[string]any{
213 "MergeRequest": obj("Merge request.", map[string]any{
214 "id": integer("Internal id."),
215 "iid": integer("Merge request number in the project."),
216 "title": str("Title."),
217 "description": str("Description."),
218 "source_branch": str("Source branch."),
219 "target_branch": str("Target branch."),
220 "author": str("Author username."),
221 "state": str("open, closed or merged."),
222 "draft": boolean("Draft merge request."),
223 "labels": str("Comma-separated label names."),
224 "remove_source_branch": boolean("Delete the source branch after a successful merge."),
225 "squash": boolean("Squash commits when merging."),
226 "squash_commit_message": str("Commit message used when squash is enabled. Empty uses the title."),
227 "web_url": str("Full page URL. An empty base URL yields a path."),
228 "created_at": when,
229 "updated_at": when,
230 }),
231 "MergeRequestCreate": obj("Fields for a new merge request. Omitted remove_source_branch means true. Omitted squash means false.", map[string]any{
232 "title": str("Title."),
233 "description": str("Description."),
234 "source_branch": str("Source branch."),
235 "target_branch": str("Target branch."),
236 "draft": boolean("Create as draft."),
237 "remove_source_branch": boolean("Delete the source branch after merge. Omitted means true."),
238 "squash": boolean("Squash commits. Omitted means false."),
239 "squash_commit_message": str("Squash commit message. Empty uses the merge request title."),
240 }),
241 "MergeRequestUpdate": obj("Fields to change on a merge request. Omitted merge options keep the stored value.", map[string]any{
242 "title": str("Title."),
243 "description": str("Description."),
244 "labels": str("Comma-separated label names."),
245 "remove_source_branch": boolean("Delete the source branch after merge."),
246 "squash": boolean("Squash commits."),
247 "squash_commit_message": str("Squash commit message."),
248 }),
249 "MergeRequestMerge": obj("Merge options for this attempt. Omitted fields keep the stored value.", map[string]any{
250 "remove_source_branch": boolean("Delete the source branch after merge."),
251 "squash": boolean("Squash commits."),
252 "squash_commit_message": str("Squash commit message."),
253 }),
254 "MergeResult": obj("Result of a merge.", map[string]any{
255 "state": str("merged."),
256 "source_branch_removed": boolean("True when the source branch was deleted."),
257 "source_branch_skip": str("Empty when the branch was removed. Otherwise disabled, protected, default, forbidden, missing or error."),
258 "web_url": str("Full page URL of the merge request."),
259 }),
260 "MergeState": obj("State after close or reopen.", map[string]any{
261 "state": str("open or closed."),
262 "web_url": str("Full page URL of the merge request."),
263 }),
264 "Issue": obj("Issue. The list omits notes.", map[string]any{
265 "id": integer("Issue number in the project."),
266 "title": str("Title."),
267 "description": str("Description."),
268 "status": str("open or closed."),
269 "confidential": boolean("Hidden from users who cannot triage."),
270 "author": str("Author username."),
271 "assignees": strArr("Assignee usernames."),
272 "labels": strArr("Label names."),
273 "milestone": str("Milestone title."),
274 "due_date": str("Due date, YYYY-MM-DD, or empty."),
275 "created_at": when,
276 "updated_at": when,
277 "closed_at": when,
278 "web_url": str("Full page URL. An empty base URL yields a path."),
279 "notes": map[string]any{"type": "array", "items": schemaRef("IssueNote"), "description": "Notes. Omitted on the list."},
280 }),
281 "IssueNote": obj("Issue note.", map[string]any{
282 "id": integer("Note id."),
283 "author": str("Author username."),
284 "body": str("Note text."),
285 "created_at": when,
286 }),
287 "IssueList": obj("Issue list.", map[string]any{
288 "issues": map[string]any{"type": "array", "items": schemaRef("Issue")},
289 }),
290 "IssueWrite": obj("Fields to create or update an issue. Omitted fields stay unchanged on update.", map[string]any{
291 "title": str("Title. Required when creating."),
292 "description": str("Description."),
293 "state": str("open or closed."),
294 "confidential": boolean("Confidential issue."),
295 "labels": strArr("Label names."),
296 "assignees": strArr("Assignee usernames."),
297 "milestone": str("Milestone title."),
298 "due_date": str("Due date, YYYY-MM-DD, or empty."),
299 }),
300 "IssueNoteCreate": obj("New issue note. A body that is only quick actions returns the issue instead of a note.", map[string]any{
301 "body": str("Note text, including optional quick actions."),
302 }),
303 "Pipeline": obj("Pipeline.", map[string]any{
304 "id": integer("Pipeline id."),
305 "sha": str("Commit SHA."),
306 "ref": str("Git ref, for example refs/heads/master."),
307 "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."),
308 "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."),
309 "cancel_reason": str("For status canceled: superseded (a newer pipeline started for the same ref; also for manual jobs that expired that way), stale (a manual job expired because its pipeline waited only for manual action longer than stale_manual_days) or manual. Null otherwise. Only in list and get responses."),
310 "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."},
311 "source": str("Trigger source."),
312 "actor": str("Username that started the pipeline."),
313 "created_at": when,
314 "started_at": when,
315 "finished_at": when,
316 "web_url": str("Full page URL. An empty base URL yields a path."),
317 }),
318 "PipelineCreate": obj("Start a pipeline.", map[string]any{
319 "ref": str("Branch, tag or full ref to run."),
320 }),
321 "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. An omitted or empty body uses failed.", map[string]any{
322 "mode": map[string]any{
323 "type": "string",
324 "description": "all or failed. Omitted or empty means failed.",
325 "enum": []any{"all", "failed"},
326 "default": "failed",
327 },
328 }),
329 "Job": obj("CI job.", map[string]any{
330 "id": integer("Job id."),
331 "name": str("Job name."),
332 "stage": str("Stage name."),
333 "status": str("Job status."),
334 "when": str("When the job runs."),
335 "display_status": str("Status as the UI shows it: obsolete for a job canceled because a newer pipeline started for the same ref or an expired manual job, otherwise equal to status."),
336 "cancel_reason": str("For status canceled: superseded, stale (expired manual job) or manual. Null otherwise."),
337 "do_not_interrupt": boolean("doNotInterrupt is set: the job is never stopped automatically, and cancelling it while it runs needs force=true."),
338 "failure_reason": str("For status failed: job_execution_timeout, script_failure or runner_system_failure when known. Null otherwise."),
339 "allow_failure": boolean("A failed job does not fail the pipeline."),
340 "started_at": when,
341 "finished_at": when,
342 }),
343 "Branch": obj("Branch tip. Create and rename responses only include name.", map[string]any{
344 "name": str("Branch name."),
345 "commit": str("Tip commit SHA."),
346 "subject": str("Tip commit subject."),
347 "date": str("Tip commit date."),
348 "default": boolean("True for the default branch."),
349 }),
350 "BranchCreate": obj("Create a branch.", map[string]any{
351 "name": str("New branch name."),
352 "from": str("Existing branch or commit to start from."),
353 }),
354 "BranchUpdate": obj("Rename a branch. On PUT /repository/branches the current name is the name query. confirm may then be omitted and defaults to that name.", map[string]any{
355 "name": str("New branch name."),
356 "confirm": str("Current branch name, repeated as confirmation. Required when the current name is in the path."),
357 }),
358 "BranchDelete": obj("Delete a branch. On DELETE /repository/branches the name may be the name query or this name field. confirm may then be omitted and defaults to the name.", map[string]any{
359 "name": str("Branch name, when not in the path or the name query."),
360 "confirm": str("Branch name, repeated as confirmation. Required when the name is in the path."),
361 }),
362 "Webhook": obj("Webhook.", map[string]any{
363 "id": integer("Webhook id."),
364 "name": str("Display name."),
365 "preset": str("Preset name, or empty for a custom hook."),
366 "url": str("URL template."),
367 "method": str("HTTP method."),
368 "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."),
369 "branch_filter": str("Branch filter. Empty matches every branch."),
370 "active": boolean("Hook is enabled."),
371 }),
372 "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{
373 "id": integer("User id."),
374 "username": str("Username."),
375 "name": str("Display name. Empty when unset."),
376 "bio": str("Profile text. Empty when unset."),
377 "avatar_url": str("Avatar URL."),
378 "created_at": when,
379 "web_url": str("Profile page at /users/{username}."),
380 "instance_admin": boolean("Instance administrator. Only on the signed-in user."),
381 "language": str("Interface language. Only on the signed-in user."),
382 "counts": obj("Totals the viewer is allowed to see.", map[string]any{
383 "repos": integer("Owned repositories visible to the viewer."),
384 "groups": integer("Groups the user belongs to that the viewer may see."),
385 "contributions": integer("Contributions in the last 12 months in repositories the viewer may see."),
386 }),
387 "repos": map[string]any{"type": "array", "description": "Owned repositories visible to the viewer.", "items": schemaRef("UserRepo")},
388 "groups": map[string]any{"type": "array", "description": "Groups visible to the viewer.", "items": schemaRef("UserGroup")},
389 }),
390 "UserUpdate": obj("Fields to change on the signed-in user. Omitted fields stay unchanged.", map[string]any{
391 "name": str("Display name. Empty clears it."),
392 "bio": str("Profile text. Empty clears it. Newlines are kept."),
393 "language": str("Interface language."),
394 }),
395 "UserRepo": obj("Repository on a user profile.", map[string]any{
396 "id": integer("Repository id."),
397 "name": str("Repository name."),
398 "path": str("Full path, owner/name."),
399 "description": str("Description."),
400 "visibility": str("public or private."),
401 "web_url": str("Full page URL."),
402 }),
403 "UserGroup": obj("Group on a user profile.", map[string]any{
404 "id": integer("Group id."),
405 "name": str("Group name."),
406 "path": str("Group path."),
407 "description": str("Description."),
408 "visibility": str("public or private."),
409 "web_url": str("Full page URL."),
410 }),
411 "WebhookCreate": obj("Create a webhook. Preset fields depend on the chosen preset.", map[string]any{
412 "name": str("Display name."),
413 "preset": str("Preset name."),
414 "branch_filter": str("Branch filter."),
415 "events": strArr("Events, see the list on the webhook schema."),
416 "url": str("URL template."),
417 "username": str("Username for the preset."),
418 "avatar": str("Avatar URL."),
419 "icon": str("Icon URL or emoji."),
420 "alias": str("Alias."),
421 "token": str("Name of the secret that holds the token. The value is never returned."),
422 "chat": str("Chat id."),
423 "server": str("Server URL."),
424 "topic": str("Topic."),
425 "homeserver": str("Matrix homeserver."),
426 "room": str("Matrix room."),
427 "method": str("HTTP method."),
428 "content_type": str("Content type."),
429 "headers": str("Extra headers."),
430 "body": str("Body template."),
431 }),
432 "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{
433 "name": str("Display name."),
434 "preset": str("Preset name."),
435 "branch_filter": str("Branch filter."),
436 "events": strArr("Events, see the list on the webhook schema."),
437 "active": boolean("Enable or disable the hook."),
438 "url": str("URL template."),
439 "username": str("Username for the preset."),
440 "avatar": str("Avatar URL."),
441 "icon": str("Icon URL or emoji."),
442 "alias": str("Alias."),
443 "token": str("Name of the secret that holds the token. Empty keeps the current one."),
444 "chat": str("Chat id."),
445 "server": str("Server URL."),
446 "topic": str("Topic."),
447 "homeserver": str("Matrix homeserver."),
448 "room": str("Matrix room."),
449 "method": str("HTTP method."),
450 "content_type": str("Content type."),
451 "headers": str("Extra headers. Empty keeps the current headers."),
452 "body": str("Body template."),
453 }),
454 "GroupDelete": obj("Delete an empty group. Fails with 409 while the group still has repositories (no force). Removes members, invitations, group secrets, webhooks and approval rules, and revokes group runners. Group maintainers and admins only.", map[string]any{
455 "confirm": str("Group name or path, to confirm."),
456 }),
457 "Secret": obj("A secret. Values are never returned.", map[string]any{
458 "name": str("Secret name."),
459 "protected": boolean("Only injected on protected refs."),
460 "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."),
461 "created_at": str("Creation time (RFC 3339)."),
462 }),
463 "SecretWrite": obj("Create or replace a secret.", map[string]any{
464 "name": str("Secret name."),
465 "value": str("Secret value. Never returned."),
466 "protected": boolean("Only injected on protected refs."),
467 "expand": boolean("Expand $NAME references in the value at job time. Default false; omitted on update keeps the stored setting."),
468 }),
469 "SecretName": obj("The stored secret name.", map[string]any{"name": str("Secret name.")}),
470 "ForkedProject": obj("A project (same fields as GET /projects/{owner}/{repo}). The fork response adds forked_from.", map[string]any{
471 "path_with_namespace": str("owner/name."),
472 "visibility": str("public or private."),
473 "forked_from": str("Upstream owner/name (only in the fork response)."),
474 }),
475 "ForkMergeRequest": obj("Merge request from a fork branch into upstream. The merge request lives in upstream and is merged there by its maintainers. Pipelines for it run in upstream on forks/<fork id>/<branch> without any group or project secrets.", map[string]any{
476 "source_branch": str("Branch in the fork."),
477 "target_branch": str("Branch in upstream. Default: upstream default branch."),
478 "title": str("Title."),
479 "description": str("Description."),
480 "draft": boolean("Open as draft."),
481 }),
482 "SyncUpstream": obj("Fast-forward a fork branch to the same branch in upstream. Never forces; a diverged branch gives 409.", map[string]any{
483 "branch": str("Branch to sync. Default: the fork's default branch."),
484 }),
485 "SyncResult": obj("Outcome of an upstream sync.", map[string]any{
486 "branch": str("Branch."),
487 "before": str("Fork commit before (empty if the branch was new)."),
488 "after": str("Fork commit after."),
489 "up_to_date": boolean("Nothing to do."),
490 }),
491 "ForkCreate": obj("Fork a project with all branches and tags. Objects are hard-linked on the server disk. A fork of a private project is private and cannot be made public. The response adds forked_from.", map[string]any{
492 "namespace": str("Group path where you are at least developer. Empty: your own account."),
493 "name": str("Optional new name. Default keeps the upstream name. 409 if it already exists."),
494 }),
495 "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{
496 "name": str("Secret name."),
497 "group": str("Path of the group it comes from."),
498 "protected": boolean("Only injected on protected refs."),
499 "overridden": boolean("A project secret with the same name replaces it."),
500 }),
501 "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{
502 "target_type": str("project or group."),
503 "target": str("Target path: owner/project or group path."),
504 "name": str("Optional new name. Default keeps the name."),
505 "events": strArr("Optional event filter. Default keeps the events."),
506 }),
507 "WebhookCopyResult": obj("The new webhook plus the names (never values) of copied secrets.", map[string]any{
508 "id": integer("New webhook id."),
509 "name": str("Display name."),
510 "preset": str("Preset name."),
511 "url": str("URL template."),
512 "method": str("HTTP method."),
513 "events": strArr("Events."),
514 "branch_filter": str("Branch filter."),
515 "active": boolean("Hook is enabled."),
516 "scope": str("repo or group."),
517 "copied_secrets": strArr("Names of secrets copied to the target."),
518 "missing_secrets": strArr("Referenced secret names found nowhere; add them in the target."),
519 }),
520 "Project": obj("A project.", map[string]any{
521 "id": integer("Internal id."),
522 "path": str("owner/name."),
523 "name": str("Project name."),
524 "owner": str("User or group path."),
525 "description": str("Description."),
526 "visibility": str("public or private."),
527 "default_branch": str("Default branch (symbolic HEAD)."),
528 "release_visibility": str("inherit, private or public."),
529 "ci_paused": boolean("When true, no new pipelines are queued."),
530 "stale_manual_days": integer("Override for expiring manual jobs. -1 inherits the instance setting. Only in the get/update response."),
531 }),
532 "ProjectCreate": obj("Create a project.", map[string]any{
533 "name": str("Project name. Required."),
534 "description": str("Description."),
535 "group": str("Group path. Empty: under your account."),
536 "visibility": str("public or private."),
537 "initialize_with_readme": boolean("Create an initial README commit."),
538 }),
539 "ProjectUpdate": obj("Fields to change on a project. Omitted fields stay unchanged.", map[string]any{
540 "description": str("Description."),
541 "visibility": str("public or private."),
542 "release_visibility": str("inherit, private or public."),
543 "stale_manual_days": integer("Override for expiring manual jobs. -1 inherits the instance setting."),
544 "default_branch": str("Existing branch to make the default. Updates symbolic HEAD and the stored default."),
545 "ci_paused": boolean("When true, no new pipelines are queued (pushes, merge requests, manual runs). Already running or queued jobs keep going."),
546 }),
547 "LogoUpload": obj("Multipart logo upload. Field name is logo. PNG, JPEG, GIF, SVG or ICO.", map[string]any{
548 "logo": map[string]any{"type": "string", "format": "binary", "description": "Logo file."},
549 }),
550 "LogoResult": obj("Logo stored.", map[string]any{"logo": boolean("True when the logo was saved.")}),
551 "ProtectedPattern": obj("A protected branch or tag pattern.", map[string]any{
552 "pattern": str("Git ref pattern to protect."),
553 }),
554 "CILint": obj("Lint a CI file. Provide body, or ref to read blue-ci-cd.yml from the repository.", map[string]any{
555 "body": str("CI YAML to lint. Empty: use the file at ref."),
556 "ref": str("Branch, tag or commit to read the CI file from when body is empty."),
557 }),
558 "CILintResult": obj("Lint result.", map[string]any{
559 "status": str("Human-readable status."),
560 "statusClass": str("CSS class for the status."),
561 "errors": strArr("Errors."),
562 "warnings": strArr("Warnings."),
563 "issues": integer("Number of issues."),
564 "lines": strArr("Rendered source lines."),
565 "bad": map[string]any{"type": "array", "items": integer("1-based line number."), "description": "Lines with errors."},
566 }),
567 }
568}
569
570func obj(desc string, props map[string]any) map[string]any {
571 return map[string]any{"type": "object", "description": desc, "properties": props}
572}
573
574func str(desc string) map[string]any {
575 return map[string]any{"type": "string", "description": desc}
576}
577
578func strArr(desc string) map[string]any {
579 return map[string]any{"type": "array", "description": desc, "items": map[string]any{"type": "string"}}
580}
581
582func boolean(desc string) map[string]any {
583 return map[string]any{"type": "boolean", "description": desc}
584}
585
586func integer(desc string) map[string]any {
587 return map[string]any{"type": "integer", "format": "int64", "description": desc}
588}