From 52d17c410ae6d5ca58c97c0157cab56a01f88259 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?=E2=98=99=E2=97=A6=20The=20Tablet=20=E2=9D=80=20GamerGirla?= =?UTF-8?q?ndCo=20=E2=97=A6=E2=9D=A7?= Date: Thu, 14 Aug 2025 16:23:42 -0400 Subject: [PATCH] add appropriate swagger definitions --- modules/structs/repo_group.go | 7 +- routers/api/v1/swagger/options.go | 9 + routers/api/v1/swagger/repo_group.go | 17 ++ templates/swagger/v1_json.tmpl | 377 ++++++++++++++++++++++++++- 4 files changed, 405 insertions(+), 5 deletions(-) create mode 100644 routers/api/v1/swagger/repo_group.go diff --git a/modules/structs/repo_group.go b/modules/structs/repo_group.go index 0bc64fd253..0565ce3fbf 100644 --- a/modules/structs/repo_group.go +++ b/modules/structs/repo_group.go @@ -1,7 +1,6 @@ package structs // Group represents a group of repositories and subgroups in an organization -// swagger:model type Group struct { ID int64 `json:"id"` Owner *User `json:"owner"` @@ -14,7 +13,7 @@ type Group struct { SortOrder int `json:"sort_order"` } -// NewGroupOption - options for creating a new group in an organization +// NewGroupOption represents options for creating a new group in an organization // swagger:model type NewGroupOption struct { // the name for the newly created group @@ -27,7 +26,7 @@ type NewGroupOption struct { Visibility VisibleType `json:"visibility"` } -// MoveGroupOption - options for changing a group or repo's parent and sort order +// MoveGroupOption represents options for changing a group or repo's parent and sort order // swagger:model type MoveGroupOption struct { // the new parent group. can be 0 to specify no parent @@ -38,7 +37,7 @@ type MoveGroupOption struct { NewPos *int `json:"newPos,omitempty"` } -// EditGroupOption - options for editing a repository group +// EditGroupOption represents options for editing a repository group // swagger:model type EditGroupOption struct { // the new name of the group diff --git a/routers/api/v1/swagger/options.go b/routers/api/v1/swagger/options.go index f66cef61df..21a6fab4cb 100644 --- a/routers/api/v1/swagger/options.go +++ b/routers/api/v1/swagger/options.go @@ -230,4 +230,13 @@ type swaggerParameterBodies struct { // in:body LockIssueOption api.LockIssueOption + + // in:body + NewGroupOption api.NewGroupOption + + // in:body + EditGroupOption api.EditGroupOption + + // in:body + MoveGroupOption api.MoveGroupOption } diff --git a/routers/api/v1/swagger/repo_group.go b/routers/api/v1/swagger/repo_group.go new file mode 100644 index 0000000000..b9a0766f34 --- /dev/null +++ b/routers/api/v1/swagger/repo_group.go @@ -0,0 +1,17 @@ +package swagger + +import api "code.gitea.io/gitea/modules/structs" + +// Group +// swagger:response Group +type swaggerResponseGroup struct { + // in:body + Body api.Group `json:"body"` +} + +// GroupList +// swagger:response GroupList +type swaggerResponseGroupList struct { + // in:body + Body []api.Group `json:"body"` +} diff --git a/templates/swagger/v1_json.tmpl b/templates/swagger/v1_json.tmpl index c4342c5a7d..c58873d7c7 100644 --- a/templates/swagger/v1_json.tmpl +++ b/templates/swagger/v1_json.tmpl @@ -1316,6 +1316,199 @@ } } }, + "/groups/{group_id}": { + "get": { + "produces": [ + "application/json" + ], + "tags": [ + "repository-group" + ], + "summary": "gets the repos contained within a group", + "operationId": "groupRepos", + "parameters": [ + { + "type": "integer", + "format": "int64", + "description": "id of the group to retrieve", + "name": "group_id", + "in": "path", + "required": true + } + ], + "responses": { + "200": { + "$ref": "#/responses/Group" + }, + "404": { + "$ref": "#/responses/notFound" + }, + "422": { + "$ref": "#/responses/validationError" + } + } + }, + "delete": { + "produces": [ + "application/json" + ], + "tags": [ + "repositoryGroup" + ], + "summary": "Delete a repository group", + "operationId": "groupDelete", + "parameters": [ + { + "type": "string", + "description": "id of the group to delete", + "name": "group_id", + "in": "path", + "required": true + } + ], + "responses": { + "204": { + "$ref": "#/responses/empty" + }, + "403": { + "$ref": "#/responses/forbidden" + }, + "404": { + "$ref": "#/responses/notFound" + } + } + }, + "patch": { + "consumes": [ + "application/json" + ], + "produces": [ + "application/json" + ], + "tags": [ + "repository-group" + ], + "summary": "edits a group in an organization. only fields that are set will be changed.", + "operationId": "groupEdit", + "parameters": [ + { + "type": "integer", + "format": "int64", + "description": "id of the group to edit", + "name": "group_id", + "in": "path", + "required": true + }, + { + "name": "body", + "in": "body", + "required": true, + "schema": { + "$ref": "#/definitions/EditGroupOption" + } + } + ], + "responses": { + "200": { + "$ref": "#/responses/Group" + }, + "404": { + "$ref": "#/responses/notFound" + }, + "422": { + "$ref": "#/responses/validationError" + } + } + } + }, + "/groups/{group_id}/move": { + "post": { + "consumes": [ + "application/json" + ], + "produces": [ + "application/json" + ], + "tags": [ + "repository-group" + ], + "summary": "move a group to a different parent group", + "operationId": "groupMove", + "parameters": [ + { + "type": "integer", + "format": "int64", + "description": "id of the group to move", + "name": "group_id", + "in": "path", + "required": true + }, + { + "name": "body", + "in": "body", + "required": true, + "schema": { + "$ref": "#/definitions/MoveGroupOption" + } + } + ], + "responses": { + "200": { + "$ref": "#/responses/Group" + }, + "404": { + "$ref": "#/responses/notFound" + }, + "422": { + "$ref": "#/responses/validationError" + } + } + } + }, + "/groups/{group_id}/new": { + "post": { + "consumes": [ + "application/json" + ], + "produces": [ + "application/json" + ], + "tags": [ + "repository-group" + ], + "summary": "create a subgroup inside a group", + "operationId": "groupNewSubGroup", + "parameters": [ + { + "type": "integer", + "format": "int64", + "description": "id of the group to create a subgroup in", + "name": "group_id", + "in": "path", + "required": true + }, + { + "name": "body", + "in": "body", + "required": true, + "schema": { + "$ref": "#/definitions/CreateGroupOption" + } + } + ], + "responses": { + "201": { + "$ref": "#/responses/Group" + }, + "404": { + "$ref": "#/responses/notFound" + }, + "422": { + "$ref": "#/responses/validationError" + } + } + } + }, "/label/templates": { "get": { "produces": [ @@ -2858,6 +3051,49 @@ } } }, + "/orgs/{org}/groups/new": { + "post": { + "consumes": [ + "application/json" + ], + "produces": [ + "application/json" + ], + "tags": [ + "repository-group" + ], + "summary": "create a root-level repository group for an organization", + "operationId": "groupNew", + "parameters": [ + { + "type": "string", + "description": "name of the organization", + "name": "org", + "in": "path", + "required": true + }, + { + "name": "body", + "in": "body", + "required": true, + "schema": { + "$ref": "#/definitions/CreateGroupOption" + } + } + ], + "responses": { + "201": { + "$ref": "#/responses/Group" + }, + "404": { + "$ref": "#/responses/notFound" + }, + "422": { + "$ref": "#/responses/validationError" + } + } + } + }, "/orgs/{org}/hooks": { "get": { "produces": [ @@ -24011,6 +24247,12 @@ "type": "string", "x-go-name": "Gitignores" }, + "group_id": { + "description": "GroupID of the group which will contain this repository. ignored if the repo owner is not an organization.", + "type": "integer", + "format": "int64", + "x-go-name": "GroupID" + }, "issue_labels": { "description": "Label-Set to use", "type": "string", @@ -24700,6 +24942,26 @@ }, "x-go-package": "code.gitea.io/gitea/modules/structs" }, + "EditGroupOption": { + "description": "EditGroupOption represents options for editing a repository group", + "type": "object", + "properties": { + "description": { + "description": "the new description of the group", + "type": "string", + "x-go-name": "Description" + }, + "name": { + "description": "the new name of the group", + "type": "string", + "x-go-name": "Name" + }, + "visibility": { + "$ref": "#/definitions/VisibleType" + } + }, + "x-go-package": "code.gitea.io/gitea/modules/structs" + }, "EditHookOption": { "description": "EditHookOption options when modify one hook", "type": "object", @@ -26113,6 +26375,53 @@ }, "x-go-package": "code.gitea.io/gitea/modules/structs" }, + "Group": { + "description": "Group represents a group of repositories and subgroups in an organization", + "type": "object", + "properties": { + "description": { + "type": "string", + "x-go-name": "Description" + }, + "id": { + "type": "integer", + "format": "int64", + "x-go-name": "ID" + }, + "link": { + "type": "string", + "x-go-name": "Link" + }, + "name": { + "type": "string", + "x-go-name": "Name" + }, + "num_repos": { + "type": "integer", + "format": "int64", + "x-go-name": "NumRepos" + }, + "num_subgroups": { + "type": "integer", + "format": "int64", + "x-go-name": "NumSubgroups" + }, + "owner": { + "$ref": "#/definitions/User" + }, + "parentGroupID": { + "type": "integer", + "format": "int64", + "x-go-name": "ParentGroupID" + }, + "sort_order": { + "type": "integer", + "format": "int64", + "x-go-name": "SortOrder" + } + }, + "x-go-package": "code.gitea.io/gitea/modules/structs" + }, "Hook": { "description": "Hook a hook is a web hook when one repository changed", "type": "object", @@ -26977,6 +27286,51 @@ }, "x-go-package": "code.gitea.io/gitea/modules/structs" }, + "MoveGroupOption": { + "description": "MoveGroupOption represents options for changing a group or repo's parent and sort order", + "type": "object", + "required": [ + "newParent" + ], + "properties": { + "newParent": { + "description": "the new parent group. can be 0 to specify no parent", + "type": "integer", + "format": "int64", + "x-go-name": "NewParent" + }, + "newPos": { + "description": "the position of this group in its new parent", + "type": "integer", + "format": "int64", + "x-go-name": "NewPos" + } + }, + "x-go-package": "code.gitea.io/gitea/modules/structs" + }, + "NewGroupOption": { + "description": "NewGroupOption represents options for creating a new group in an organization", + "type": "object", + "required": [ + "name" + ], + "properties": { + "description": { + "description": "the description of the newly created group", + "type": "string", + "x-go-name": "Description" + }, + "name": { + "description": "the name for the newly created group", + "type": "string", + "x-go-name": "Name" + }, + "visibility": { + "$ref": "#/definitions/VisibleType" + } + }, + "x-go-package": "code.gitea.io/gitea/modules/structs" + }, "NewIssuePinsAllowed": { "description": "NewIssuePinsAllowed represents an API response that says if new Issue Pins are allowed", "type": "object", @@ -29685,6 +30039,12 @@ }, "x-go-package": "code.gitea.io/gitea/modules/structs" }, + "VisibleType": { + "description": "VisibleType defines the visibility of user and org", + "type": "integer", + "format": "int64", + "x-go-package": "code.gitea.io/gitea/modules/structs" + }, "WatchInfo": { "description": "WatchInfo represents an API watch status of one repository", "type": "object", @@ -30230,6 +30590,21 @@ } } }, + "Group": { + "description": "Group", + "schema": { + "$ref": "#/definitions/Group" + } + }, + "GroupList": { + "description": "GroupList", + "schema": { + "type": "array", + "items": { + "$ref": "#/definitions/Group" + } + } + }, "Hook": { "description": "Hook", "schema": { @@ -30941,7 +31316,7 @@ "parameterBodies": { "description": "parameterBodies", "schema": { - "$ref": "#/definitions/LockIssueOption" + "$ref": "#/definitions/MoveGroupOption" } }, "redirect": {