From 1b47d915bc1dc442c125386245a8876d46763d5b Mon Sep 17 00:00:00 2001 From: eyad-hussein Date: Mon, 15 Jul 2024 13:33:26 +0300 Subject: [PATCH] docs: create swagger api documentation for endpoints --- modules/structs/issue.go | 14 + modules/structs/project.go | 16 + modules/structs/project_column.go | 8 + routers/api/v1/api.go | 8 +- routers/api/v1/shared/project.go | 564 ++++++++++++++--- routers/api/v1/swagger/options.go | 15 + routers/api/v1/swagger/project.go | 14 + templates/swagger/v1_json.tmpl | 980 +++++++++++++++++++++++++++++- 8 files changed, 1546 insertions(+), 73 deletions(-) diff --git a/modules/structs/issue.go b/modules/structs/issue.go index 3c06e383560..232d3cc08fe 100644 --- a/modules/structs/issue.go +++ b/modules/structs/issue.go @@ -115,6 +115,20 @@ type EditIssueOption struct { RemoveDeadline *bool `json:"unset_due_date"` } +// MoveIssuesOption options for moving issues +type MovedIssuesOption struct { + Issues []struct { + IssueID int64 `json:"issueID"` + Sorting int64 `json:"sorting"` + } `json:"issues"` +} + +// UpdateIssuesOption options for updating issues +type UpdateIssuesOption struct { + ProjectID int64 `json:"project_id"` + Issues []int64 `json:"issues"` +} + // EditDeadlineOption options for creating a deadline type EditDeadlineOption struct { // required:true diff --git a/modules/structs/project.go b/modules/structs/project.go index 1b850504d9d..02ebd2fe523 100644 --- a/modules/structs/project.go +++ b/modules/structs/project.go @@ -21,6 +21,7 @@ type Project struct { ClosedDateUnix int64 `json:"closed_date_unix"` } +// CreateProjectOption options for creating a project type CreateProjectOption struct { // required:true Title string `json:"title" binding:"Required;MaxSize(100)"` @@ -28,3 +29,18 @@ type CreateProjectOption struct { TemplateType uint8 `json:"template_type"` CardType uint8 `json:"card_type"` } + +// EditProjectOption options for editing a project +type EditProjectOption struct { + Title string `json:"title" binding:"MaxSize(100)"` + Content string `json:"content"` + CardType uint8 `json:"card_type"` +} + +// MoveColumnsOption options for moving columns +type MovedColumnsOption struct { + Columns []struct { + ColumnID int64 `json:"columnID"` + Sorting int64 `json:"sorting"` + } `json:"columns"` +} diff --git a/modules/structs/project_column.go b/modules/structs/project_column.go index 4138717d776..b4e5d181442 100644 --- a/modules/structs/project_column.go +++ b/modules/structs/project_column.go @@ -12,6 +12,14 @@ type Column struct { // EditProjectColumnOption options for editing a project column type EditProjectColumnOption struct { + Title string `binding:"MaxSize(100)"` + Sorting int8 + Color string `binding:"MaxSize(7)"` +} + +// CreateProjectColumnOption options for creating a project column +type CreateProjectColumnOption struct { + // required:true Title string `binding:"Required;MaxSize(100)"` Sorting int8 Color string `binding:"MaxSize(7)"` diff --git a/routers/api/v1/api.go b/routers/api/v1/api.go index f621456a5d1..6ea6c096fe1 100644 --- a/routers/api/v1/api.go +++ b/routers/api/v1/api.go @@ -1026,9 +1026,9 @@ func Routes() *web.Router { m.Group("", func() { m.Post("", bind(api.CreateProjectOption{}), project_shared.ProjectHandler("org", project_shared.CreateProject)) m.Group("/{id}", func() { - m.Post("", bind(api.EditProjectColumnOption{}), project_shared.ProjectHandler("org", project_shared.AddColumnToProject)) + m.Post("", bind(api.CreateProjectColumnOption{}), project_shared.ProjectHandler("org", project_shared.AddColumnToProject)) m.Delete("", project_shared.ProjectHandler("org", project_shared.DeleteProject)) - m.Put("", bind(api.CreateProjectOption{}), project_shared.ProjectHandler("org", project_shared.EditProject)) + m.Put("", bind(api.EditProjectOption{}), project_shared.ProjectHandler("org", project_shared.EditProject)) m.Post("/move", project_shared.MoveColumns) m.Post("/{action:open|close}", project_shared.ChangeProjectStatus) @@ -1055,9 +1055,9 @@ func Routes() *web.Router { m.Group("", func() { m.Post("", bind(api.CreateProjectOption{}), project_shared.ProjectHandler("repo", project_shared.CreateProject)) m.Group("/{id}", func() { - m.Post("", bind(api.EditProjectColumnOption{}), project_shared.ProjectHandler("repo", project_shared.AddColumnToProject)) + m.Post("", bind(api.CreateProjectColumnOption{}), project_shared.ProjectHandler("repo", project_shared.AddColumnToProject)) m.Delete("", project_shared.ProjectHandler("repo", project_shared.DeleteProject)) - m.Put("", bind(api.CreateProjectOption{}), project_shared.ProjectHandler("repo", project_shared.EditProject)) + m.Put("", bind(api.EditProjectOption{}), project_shared.ProjectHandler("repo", project_shared.EditProject)) m.Post("/move", project_shared.MoveColumns) m.Post("/{action:open|close}", project_shared.ChangeProjectStatus) diff --git a/routers/api/v1/shared/project.go b/routers/api/v1/shared/project.go index 4858ec06763..31c2e34c98f 100644 --- a/routers/api/v1/shared/project.go +++ b/routers/api/v1/shared/project.go @@ -41,9 +41,10 @@ func ProjectHandler(model string, fn func(ctx *context.APIContext, model string) // CreateProject creates a new project func CreateProject(ctx *context.APIContext, model string) { - // swagger: operation POST /users/{username}/{reponame}/projects project createProject + // swagger:operation POST /{username}/{repo}/projects project createProject // --- - // summary: Create a project + // summary: Create a new project + // description: Creates a new project for a given user and repository. // consumes: // - application/json // produces: @@ -52,22 +53,30 @@ func CreateProject(ctx *context.APIContext, model string) { // - name: username // in: path // description: owner of the project - // type: string // required: true - // - name: reponame + // type: string + // - name: repo // in: path - // description: repository name - // type: string + // description: repository name. If left '-', the project will be created for the user // required: true + // type: string // - name: body // in: body + // description: Project data + // required: true // schema: // "$ref": "#/definitions/CreateProjectOption" // responses: - // "200": + // "201": // "$ref": "#/responses/Project" - // "404": - // "$ref": "#/responses/notFound" + // "403": + // "$ref": "#/responses/forbidden" + // "412": + // "$ref": "#/responses/error" + // "422": + // "$ref": "#/responses/validationError" + // "423": + // "$ref": "#/responses/repoArchivedError" err := checkModelType(model) @@ -108,6 +117,33 @@ func CreateProject(ctx *context.APIContext, model string) { // GetProjects returns a list of projects func GetProjects(ctx *context.APIContext, model string) { + // swagger:operation GET /{username}/{repo}/projects project getProjects + // --- + // summary: Get a list of projects + // description: Returns a list of projects for a given user and repository. + // produces: + // - application/json + // parameters: + // - name: username + // in: path + // description: owner of the project + // required: true + // type: string + // - name: repo + // in: path + // description: repository name. If left '-', the projects will be returned for the user + // required: true + // type: string + // responses: + // "200": + // "$ref": "#/responses/ProjectList" + // "403": + // "$ref": "#/responses/forbidden" + // "404": + // "$ref": "#/responses/notFound" + // "423": + // "$ref": "#/responses/repoArchivedError" + err := checkModelType(model) if err != nil { @@ -150,6 +186,37 @@ func GetProjects(ctx *context.APIContext, model string) { // GetProject returns a project func GetProject(ctx *context.APIContext, model string) { + // swagger:operation GET /{username}/{repo}/projects/{id} project getProject + // --- + // summary: Get a project + // produces: + // - application/json + // parameters: + // - name: username + // in: path + // description: owner of the project + // required: true + // type: string + // - name: repo + // in: path + // description: repository name. If left '-', the project will be returned for the user + // required: true + // type: string + // - name: id + // in: path + // description: project ID + // required: true + // type: integer + // responses: + // "200": + // "$ref": "#/responses/Project" + // "403": + // "$ref": "#/responses/forbidden" + // "404": + // "$ref": "#/responses/notFound" + // "423": + // "$ref": "#/responses/repoArchivedError" + err := checkModelType(model) if err != nil { @@ -193,6 +260,39 @@ func GetProject(ctx *context.APIContext, model string) { // EditProject edits a project func EditProject(ctx *context.APIContext, model string) { + // swagger:operation PUT /{username}/{repo}/projects/{id} project editProject + // --- + // summary: Edit a project + // produces: + // - application/json + // parameters: + // - name: username + // in: path + // description: owner of the project + // required: true + // type: string + // - name: repo + // in: path + // description: repository name. If left '-', the project will be edited for the user + // required: true + // type: string + // - name: id + // in: path + // description: project ID + // required: true + // type: integer + // responses: + // "201": + // "$ref": "#/responses/Project" + // "403": + // "$ref": "#/responses/forbidden" + // "404": + // "$ref": "#/responses/notFound" + // "412": + // "$ref": "#/responses/error" + // "423": + // "$ref": "#/responses/repoArchivedError" + err := checkModelType(model) if err != nil { @@ -223,6 +323,36 @@ func EditProject(ctx *context.APIContext, model string) { // DeleteProject deletes a project func DeleteProject(ctx *context.APIContext, model string) { + // swagger:operation DELETE /{username}/{repo}/projects/{id} project deleteProject + // --- + // summary: Delete a project + // description: Deletes a specific project for a given user and repository. + // parameters: + // - name: username + // in: path + // description: owner of the project + // required: true + // type: string + // - name: repo + // in: path + // description: repository name. If left '-', the project will be deleted for the user + // required: true + // type: string + // - name: id + // in: path + // description: project ID + // required: true + // type: integer + // responses: + // "204": + // "$ref": "#/responses/empty" + // "403": + // "$ref": "#/responses/forbidden" + // "404": + // "$ref": "#/responses/notFound" + // "423": + // "$ref": "#/responses/repoArchivedError" + err := checkModelType(model) if err != nil { @@ -243,11 +373,50 @@ func DeleteProject(ctx *context.APIContext, model string) { return } - ctx.JSON(http.StatusOK, map[string]any{"message": "project deleted successfully"}) + ctx.Status(http.StatusNoContent) } // ChangeProjectStatus updates the status of a project between "open" and "close" func ChangeProjectStatus(ctx *context.APIContext) { + // swagger:operation POST /{username}/{repo}/projects/{id}/{action} project changeProjectStatus + // --- + // summary: Change the status of a project + // produces: + // - application/json + // parameters: + // - name: username + // in: path + // description: owner of the project + // required: true + // type: string + // - name: repo + // in: path + // description: repository name. If left '-', the project status will be changed for the user + // required: true + // type: string + // - name: id + // in: path + // description: project ID + // required: true + // type: integer + // - name: action + // in: path + // description: action to perform (open or close) + // required: true + // type: string + // enum: + // - open + // - close + // responses: + // "204": + // "$ref": "#/responses/empty" + // "403": + // "$ref": "#/responses/forbidden" + // "404": + // "$ref": "#/responses/notFound" + // "423": + // "$ref": "#/responses/repoArchivedError" + var toClose bool switch ctx.PathParam(":action") { case "open": @@ -264,10 +433,54 @@ func ChangeProjectStatus(ctx *context.APIContext) { ctx.NotFoundOrServerError("ChangeProjectStatusByRepoIDAndID", project_model.IsErrProjectNotExist, err) return } - ctx.JSON(http.StatusOK, map[string]any{"message": "project status updated successfully"}) + ctx.Status(http.StatusNoContent) } +// AddColumnToProject adds a new column to a project func AddColumnToProject(ctx *context.APIContext, model string) { + // swagger:operation POST /{username}/{repo}/projects/{id} project addColumnToProject + // --- + // summary: Add a column to a project + // consumes: + // - application/json + // produces: + // - application/json + // parameters: + // - name: username + // in: path + // description: owner of the project + // required: true + // type: string + // - name: repo + // in: path + // description: repository name. If left '-', the column will be added to the user's project + // required: true + // type: string + // - name: id + // in: path + // description: project ID + // required: true + // type: integer + // - name: body + // in: body + // description: column data + // required: true + // schema: + // "$ref": "#/definitions/CreateProjectColumnOption" + // responses: + // "201": + // "$ref": "#/responses/Column" + // "403": + // "$ref": "#/responses/forbidden" + // "404": + // "$ref": "#/responses/notFound" + // "412": + // "$ref": "#/responses/error" + // "422": + // "$ref": "#/responses/validationError" + // "423": + // "$ref": "#/responses/repoArchivedError" + var err error err = checkModelType(model) @@ -313,7 +526,6 @@ func AddColumnToProject(ctx *context.APIContext, model string) { ctx.JSON(http.StatusCreated, convert.ToColumn(ctx, column)) } -// checkProjectColumnChangePermissions check permission func checkProjectColumnChangePermissions(ctx *context.APIContext, model string) (*project_model.Project, *project_model.Column) { if ctx.Doer == nil { ctx.JSON(http.StatusForbidden, map[string]string{ @@ -369,6 +581,54 @@ func checkProjectColumnChangePermissions(ctx *context.APIContext, model string) // EditProjectColumn allows a project column's to be updated func EditProjectColumn(ctx *context.APIContext, model string) { + // swagger:operation PUT /{username}/{repo}/projects/{id}/{column-id} project editProjectColumn + // --- + // summary: Edit a project column + // consumes: + // - application/json + // produces: + // - application/json + // parameters: + // - name: username + // in: path + // description: owner of the project + // required: true + // type: string + // - name: repo + // in: path + // description: repository name. If left '-', the column will be edited for the user's project + // required: true + // type: string + // - name: id + // in: path + // description: project ID + // required: true + // type: integer + // - name: column-id + // in: path + // description: column ID + // required: true + // type: integer + // - name: body + // in: body + // description: column data + // required: true + // schema: + // "$ref": "#/definitions/EditProjectColumnOption" + // responses: + // "201": + // "$ref": "#/responses/Column" + // "403": + // "$ref": "#/responses/forbidden" + // "404": + // "$ref": "#/responses/notFound" + // "412": + // "$ref": "#/responses/error" + // "422": + // "$ref": "#/responses/validationError" + // "423": + // "$ref": "#/responses/repoArchivedError" + err := checkModelType(model) if err != nil { @@ -400,6 +660,40 @@ func EditProjectColumn(ctx *context.APIContext, model string) { // DeleteProjectColumn allows for the deletion of a project column func DeleteProjectColumn(ctx *context.APIContext, model string) { + // swagger:operation DELETE /{username}/{repo}/projects/{id}/{column-id} project deleteProjectColumn + // --- + // summary: Delete a project column + // parameters: + // - name: username + // in: path + // description: owner of the project + // required: true + // type: string + // - name: repo + // in: path + // description: repository name. If left '-', the column will be deleted for the user's project + // required: true + // type: string + // - name: id + // in: path + // description: project ID + // required: true + // type: integer + // - name: column-id + // in: path + // description: column ID + // required: true + // type: integer + // responses: + // "204": + // "$ref": "#/responses/empty" + // "403": + // "$ref": "#/responses/forbidden" + // "404": + // "$ref": "#/responses/notFound" + // "423": + // "$ref": "#/responses/repoArchivedError" + err := checkModelType(model) if err != nil { @@ -462,11 +756,45 @@ func DeleteProjectColumn(ctx *context.APIContext, model string) { return } - ctx.JSON(http.StatusOK, map[string]string{"message": "column deleted successfully"}) + ctx.Status(http.StatusNoContent) } -// SetDefaultProjectColumn set default column for uncategorized issues/pulls +// SetDefaultProjectColumn set default column for issues/pulls func SetDefaultProjectColumn(ctx *context.APIContext, model string) { + // swagger:operation POST /{username}/{repo}/projects/{id}/{column-id}/default project setDefaultProjectColumn + // --- + // summary: Set default column for issues/pulls + // parameters: + // - name: username + // in: path + // description: owner of the project + // required: true + // type: string + // - name: repo + // in: path + // description: repository name. If left '-', the column will be set as default for the user's project + // required: true + // type: string + // - name: id + // in: path + // description: project ID + // required: true + // type: integer + // - name: column-id + // in: path + // description: column ID + // required: true + // type: integer + // responses: + // "204": + // "$ref": "#/responses/empty" + // "403": + // "$ref": "#/responses/forbidden" + // "404": + // "$ref": "#/responses/notFound" + // "423": + // "$ref": "#/responses/repoArchivedError" + err := checkModelType(model) if err != nil { @@ -484,11 +812,121 @@ func SetDefaultProjectColumn(ctx *context.APIContext, model string) { return } - ctx.JSON(http.StatusOK, map[string]string{"message": "default column set successfully"}) + ctx.Status(http.StatusNoContent) +} + +// MoveColumns moves or keeps columns in a project and sorts them inside that project +func MoveColumns(ctx *context.APIContext) { + // swagger:operation PUT /{username}/{repo}/projects/{id}/move project moveColumns + // --- + // summary: Move columns in a project + // consumes: + // - application/json + // parameters: + // - name: username + // in: path + // description: owner of the project + // required: true + // type: string + // - name: repo + // in: path + // description: repository name. If left '-', the columns will be moved for the user's project + // required: true + // type: string + // - name: id + // in: path + // description: project ID + // required: true + // type: integer + // - name: body + // in: body + // description: columns data + // required: true + // schema: + // "$ref": "#/definitions/MovedColumnsOption" + // responses: + // "204": + // "$ref": "#/responses/empty" + // "403": + // "$ref": "#/responses/forbidden" + // "404": + // "$ref": "#/responses/notFound" + // "423": + // "$ref": "#/responses/repoArchivedError" + + project, err := project_model.GetProjectByID(ctx, ctx.PathParamInt64(":id")) + if err != nil { + ctx.NotFoundOrServerError("GetProjectByID", project_model.IsErrProjectNotExist, err) + return + } + if !project.CanBeAccessedByOwnerRepo(ctx.ContextUser.ID, ctx.Repo.Repository) { + ctx.NotFound("CanBeAccessedByOwnerRepo", nil) + return + } + + form := &api.MovedColumnsOption{} + if err = json.NewDecoder(ctx.Req.Body).Decode(&form); err != nil { + ctx.ServerError("DecodeMovedColumnsForm", err) + return + } + + sortedColumnIDs := make(map[int64]int64) + for _, column := range form.Columns { + sortedColumnIDs[column.Sorting] = column.ColumnID + } + + if err = project_model.MoveColumnsOnProject(ctx, project, sortedColumnIDs); err != nil { + ctx.ServerError("MoveColumnsOnProject", err) + return + } + + ctx.Status(http.StatusNoContent) } // MoveIssues moves or keeps issues in a column and sorts them inside that column func MoveIssues(ctx *context.APIContext, model string) { + // swagger:operation POST /{username}/{repo}/projects/{id}/{column-id}/move project moveIssues + // --- + // summary: Move issues in a column + // consumes: + // - application/json + // parameters: + // - name: username + // in: path + // description: owner of the project + // required: true + // type: string + // - name: repo + // in: path + // description: repository name. + // required: true + // type: string + // - name: id + // in: path + // description: project ID + // required: true + // type: integer + // - name: column-id + // in: path + // description: column ID + // required: true + // type: integer + // - name: body + // in: body + // description: issues data + // required: true + // schema: + // "$ref": "#/definitions/MovedIssuesOption" + // responses: + // "204": + // "$ref": "#/responses/empty" + // "403": + // "$ref": "#/responses/forbidden" + // "404": + // "$ref": "#/responses/notFound" + // "423": + // "$ref": "#/responses/repoArchivedError" + err := checkModelType(model) if err != nil { @@ -529,14 +967,7 @@ func MoveIssues(ctx *context.APIContext, model string) { return } - type movedIssuesForm struct { - Issues []struct { - IssueID int64 `json:"issueID"` - Sorting int64 `json:"sorting"` - } `json:"issues"` - } - - form := &movedIssuesForm{} + form := &api.MovedIssuesOption{} if err = json.NewDecoder(ctx.Req.Body).Decode(&form); err != nil { ctx.ServerError("DecodeMovedIssuesForm", err) return @@ -576,7 +1007,7 @@ func MoveIssues(ctx *context.APIContext, model string) { return } - ctx.JSON(http.StatusOK, map[string]string{"message": "issues moved successfully"}) + ctx.Status(http.StatusNoContent) } func getActionIssues(ctx *context.APIContext, issuesIDs []int64) issues_model.IssueList { @@ -612,12 +1043,47 @@ func getActionIssues(ctx *context.APIContext, issuesIDs []int64) issues_model.Is // UpdateIssueProject change an issue's project func UpdateIssueProject(ctx *context.APIContext) { - type updateIssuesForm struct { - ProjectID int64 `json:"project_id"` - Issues []int64 `json:"issues"` - } + // swagger:operation POST /{username}/{repo}/{type}/projects project updateIssueProject + // --- + // summary: Change an issue's project + // consumes: + // - application/json + // parameters: + // - name: username + // in: path + // description: owner of the project + // required: true + // type: string + // - name: repo + // in: path + // description: repository name. + // required: true + // type: string + // - name: type + // in: path + // description: issue type (issues or pulls) + // required: true + // type: string + // enum: + // - issues + // - pulls + // - name: body + // in: body + // description: issues data + // required: true + // schema: + // "$ref": "#/definitions/UpdateIssuesOption" + // responses: + // "204": + // "$ref": "#/responses/empty" + // "403": + // "$ref": "#/responses/forbidden" + // "404": + // "$ref": "#/responses/notFound" + // "423": + // "$ref": "#/responses/repoArchivedError" - form := &updateIssuesForm{} + form := &api.UpdateIssuesOption{} if err := json.NewDecoder(ctx.Req.Body).Decode(&form); err != nil { ctx.ServerError("DecodeMovedIssuesForm", err) @@ -652,43 +1118,5 @@ func UpdateIssueProject(ctx *context.APIContext) { } } - ctx.JSON(http.StatusOK, map[string]string{"message": "issues moved successfully"}) -} - -// MoveColumns moves or keeps columns in a project and sorts them inside that project -func MoveColumns(ctx *context.APIContext) { - project, err := project_model.GetProjectByID(ctx, ctx.PathParamInt64(":id")) - if err != nil { - ctx.NotFoundOrServerError("GetProjectByID", project_model.IsErrProjectNotExist, err) - return - } - if !project.CanBeAccessedByOwnerRepo(ctx.ContextUser.ID, ctx.Repo.Repository) { - ctx.NotFound("CanBeAccessedByOwnerRepo", nil) - return - } - - type movedColumnsForm struct { - Columns []struct { - ColumnID int64 `json:"columnID"` - Sorting int64 `json:"sorting"` - } `json:"columns"` - } - - form := &movedColumnsForm{} - if err = json.NewDecoder(ctx.Req.Body).Decode(&form); err != nil { - ctx.ServerError("DecodeMovedColumnsForm", err) - return - } - - sortedColumnIDs := make(map[int64]int64) - for _, column := range form.Columns { - sortedColumnIDs[column.Sorting] = column.ColumnID - } - - if err = project_model.MoveColumnsOnProject(ctx, project, sortedColumnIDs); err != nil { - ctx.ServerError("MoveColumnsOnProject", err) - return - } - - ctx.JSON(http.StatusOK, map[string]string{"message": "columns moved successfully"}) + ctx.Status(http.StatusNoContent) } diff --git a/routers/api/v1/swagger/options.go b/routers/api/v1/swagger/options.go index c9ee3102fc6..472aea0e16d 100644 --- a/routers/api/v1/swagger/options.go +++ b/routers/api/v1/swagger/options.go @@ -208,4 +208,19 @@ type swaggerParameterBodies struct { // in:body CreateProjectOption api.CreateProjectOption + + // in:body + CreateProjectColumnOption api.CreateProjectColumnOption + + // in:body + EditProjectColumnOption api.EditProjectColumnOption + + // in:body + MovedColumnsOption api.MovedColumnsOption + + // in:body + MovedIssuesOption api.MovedIssuesOption + + // in:body + UpdateIssuesOption api.UpdateIssuesOption } diff --git a/routers/api/v1/swagger/project.go b/routers/api/v1/swagger/project.go index 90e1abd338c..26a6743e68b 100644 --- a/routers/api/v1/swagger/project.go +++ b/routers/api/v1/swagger/project.go @@ -13,3 +13,17 @@ type swaggerResponseProject struct { // in:body Body api.Project `json:"body"` } + +// ProjectList +// swagger:response ProjectList +type swaggerResponseProjectList struct { + // in:body + Body []api.Project `json:"body"` +} + +// Column +// swagger:response Column +type swaggerResponseColumn struct { + // in:body + Body api.Column `json:"body"` +} diff --git a/templates/swagger/v1_json.tmpl b/templates/swagger/v1_json.tmpl index 5c46c3c9b8a..beba3296f8a 100644 --- a/templates/swagger/v1_json.tmpl +++ b/templates/swagger/v1_json.tmpl @@ -18206,6 +18206,737 @@ } } } + }, + "/{username}/{repo}/projects": { + "get": { + "description": "Returns a list of projects for a given user and repository.", + "produces": [ + "application/json" + ], + "tags": [ + "project" + ], + "summary": "Get a list of projects", + "operationId": "getProjects", + "parameters": [ + { + "type": "string", + "description": "owner of the project", + "name": "username", + "in": "path", + "required": true + }, + { + "type": "string", + "description": "repository name. If left '-', the projects will be returned for the user", + "name": "repo", + "in": "path", + "required": true + } + ], + "responses": { + "200": { + "$ref": "#/responses/ProjectList" + }, + "403": { + "$ref": "#/responses/forbidden" + }, + "404": { + "$ref": "#/responses/notFound" + }, + "423": { + "$ref": "#/responses/repoArchivedError" + } + } + }, + "post": { + "description": "Creates a new project for a given user and repository.", + "consumes": [ + "application/json" + ], + "produces": [ + "application/json" + ], + "tags": [ + "project" + ], + "summary": "Create a new project", + "operationId": "createProject", + "parameters": [ + { + "type": "string", + "description": "owner of the project", + "name": "username", + "in": "path", + "required": true + }, + { + "type": "string", + "description": "repository name. If left '-', the project will be created for the user", + "name": "repo", + "in": "path", + "required": true + }, + { + "description": "Project data", + "name": "body", + "in": "body", + "required": true, + "schema": { + "$ref": "#/definitions/CreateProjectOption" + } + } + ], + "responses": { + "201": { + "$ref": "#/responses/Project" + }, + "403": { + "$ref": "#/responses/forbidden" + }, + "412": { + "$ref": "#/responses/error" + }, + "422": { + "$ref": "#/responses/validationError" + }, + "423": { + "$ref": "#/responses/repoArchivedError" + } + } + } + }, + "/{username}/{repo}/projects/{id}": { + "get": { + "produces": [ + "application/json" + ], + "tags": [ + "project" + ], + "summary": "Get a project", + "operationId": "getProject", + "parameters": [ + { + "type": "string", + "description": "owner of the project", + "name": "username", + "in": "path", + "required": true + }, + { + "type": "string", + "description": "repository name. If left '-', the project will be returned for the user", + "name": "repo", + "in": "path", + "required": true + }, + { + "type": "integer", + "description": "project ID", + "name": "id", + "in": "path", + "required": true + } + ], + "responses": { + "200": { + "$ref": "#/responses/Project" + }, + "403": { + "$ref": "#/responses/forbidden" + }, + "404": { + "$ref": "#/responses/notFound" + }, + "423": { + "$ref": "#/responses/repoArchivedError" + } + } + }, + "put": { + "produces": [ + "application/json" + ], + "tags": [ + "project" + ], + "summary": "Edit a project", + "operationId": "editProject", + "parameters": [ + { + "type": "string", + "description": "owner of the project", + "name": "username", + "in": "path", + "required": true + }, + { + "type": "string", + "description": "repository name. If left '-', the project will be edited for the user", + "name": "repo", + "in": "path", + "required": true + }, + { + "type": "integer", + "description": "project ID", + "name": "id", + "in": "path", + "required": true + } + ], + "responses": { + "201": { + "$ref": "#/responses/Project" + }, + "403": { + "$ref": "#/responses/forbidden" + }, + "404": { + "$ref": "#/responses/notFound" + }, + "412": { + "$ref": "#/responses/error" + }, + "423": { + "$ref": "#/responses/repoArchivedError" + } + } + }, + "post": { + "consumes": [ + "application/json" + ], + "produces": [ + "application/json" + ], + "tags": [ + "project" + ], + "summary": "Add a column to a project", + "operationId": "addColumnToProject", + "parameters": [ + { + "type": "string", + "description": "owner of the project", + "name": "username", + "in": "path", + "required": true + }, + { + "type": "string", + "description": "repository name. If left '-', the column will be added to the user's project", + "name": "repo", + "in": "path", + "required": true + }, + { + "type": "integer", + "description": "project ID", + "name": "id", + "in": "path", + "required": true + }, + { + "description": "column data", + "name": "body", + "in": "body", + "required": true, + "schema": { + "$ref": "#/definitions/CreateProjectColumnOption" + } + } + ], + "responses": { + "201": { + "$ref": "#/responses/Column" + }, + "403": { + "$ref": "#/responses/forbidden" + }, + "404": { + "$ref": "#/responses/notFound" + }, + "412": { + "$ref": "#/responses/error" + }, + "422": { + "$ref": "#/responses/validationError" + }, + "423": { + "$ref": "#/responses/repoArchivedError" + } + } + }, + "delete": { + "description": "Deletes a specific project for a given user and repository.", + "tags": [ + "project" + ], + "summary": "Delete a project", + "operationId": "deleteProject", + "parameters": [ + { + "type": "string", + "description": "owner of the project", + "name": "username", + "in": "path", + "required": true + }, + { + "type": "string", + "description": "repository name. If left '-', the project will be deleted for the user", + "name": "repo", + "in": "path", + "required": true + }, + { + "type": "integer", + "description": "project ID", + "name": "id", + "in": "path", + "required": true + } + ], + "responses": { + "204": { + "$ref": "#/responses/empty" + }, + "403": { + "$ref": "#/responses/forbidden" + }, + "404": { + "$ref": "#/responses/notFound" + }, + "423": { + "$ref": "#/responses/repoArchivedError" + } + } + } + }, + "/{username}/{repo}/projects/{id}/move": { + "put": { + "consumes": [ + "application/json" + ], + "tags": [ + "project" + ], + "summary": "Move columns in a project", + "operationId": "moveColumns", + "parameters": [ + { + "type": "string", + "description": "owner of the project", + "name": "username", + "in": "path", + "required": true + }, + { + "type": "string", + "description": "repository name. If left '-', the columns will be moved for the user's project", + "name": "repo", + "in": "path", + "required": true + }, + { + "type": "integer", + "description": "project ID", + "name": "id", + "in": "path", + "required": true + }, + { + "description": "columns data", + "name": "body", + "in": "body", + "required": true, + "schema": { + "$ref": "#/definitions/MovedColumnsOption" + } + } + ], + "responses": { + "204": { + "$ref": "#/responses/empty" + }, + "403": { + "$ref": "#/responses/forbidden" + }, + "404": { + "$ref": "#/responses/notFound" + }, + "423": { + "$ref": "#/responses/repoArchivedError" + } + } + } + }, + "/{username}/{repo}/projects/{id}/{action}": { + "post": { + "produces": [ + "application/json" + ], + "tags": [ + "project" + ], + "summary": "Change the status of a project", + "operationId": "changeProjectStatus", + "parameters": [ + { + "type": "string", + "description": "owner of the project", + "name": "username", + "in": "path", + "required": true + }, + { + "type": "string", + "description": "repository name. If left '-', the project status will be changed for the user", + "name": "repo", + "in": "path", + "required": true + }, + { + "type": "integer", + "description": "project ID", + "name": "id", + "in": "path", + "required": true + }, + { + "enum": [ + "open", + "close" + ], + "type": "string", + "description": "action to perform (open or close)", + "name": "action", + "in": "path", + "required": true + } + ], + "responses": { + "204": { + "$ref": "#/responses/empty" + }, + "403": { + "$ref": "#/responses/forbidden" + }, + "404": { + "$ref": "#/responses/notFound" + }, + "423": { + "$ref": "#/responses/repoArchivedError" + } + } + } + }, + "/{username}/{repo}/projects/{id}/{column-id}": { + "put": { + "consumes": [ + "application/json" + ], + "produces": [ + "application/json" + ], + "tags": [ + "project" + ], + "summary": "Edit a project column", + "operationId": "editProjectColumn", + "parameters": [ + { + "type": "string", + "description": "owner of the project", + "name": "username", + "in": "path", + "required": true + }, + { + "type": "string", + "description": "repository name. If left '-', the column will be edited for the user's project", + "name": "repo", + "in": "path", + "required": true + }, + { + "type": "integer", + "description": "project ID", + "name": "id", + "in": "path", + "required": true + }, + { + "type": "integer", + "description": "column ID", + "name": "column-id", + "in": "path", + "required": true + }, + { + "description": "column data", + "name": "body", + "in": "body", + "required": true, + "schema": { + "$ref": "#/definitions/EditProjectColumnOption" + } + } + ], + "responses": { + "201": { + "$ref": "#/responses/Column" + }, + "403": { + "$ref": "#/responses/forbidden" + }, + "404": { + "$ref": "#/responses/notFound" + }, + "412": { + "$ref": "#/responses/error" + }, + "422": { + "$ref": "#/responses/validationError" + }, + "423": { + "$ref": "#/responses/repoArchivedError" + } + } + }, + "delete": { + "tags": [ + "project" + ], + "summary": "Delete a project column", + "operationId": "deleteProjectColumn", + "parameters": [ + { + "type": "string", + "description": "owner of the project", + "name": "username", + "in": "path", + "required": true + }, + { + "type": "string", + "description": "repository name. If left '-', the column will be deleted for the user's project", + "name": "repo", + "in": "path", + "required": true + }, + { + "type": "integer", + "description": "project ID", + "name": "id", + "in": "path", + "required": true + }, + { + "type": "integer", + "description": "column ID", + "name": "column-id", + "in": "path", + "required": true + } + ], + "responses": { + "204": { + "$ref": "#/responses/empty" + }, + "403": { + "$ref": "#/responses/forbidden" + }, + "404": { + "$ref": "#/responses/notFound" + }, + "423": { + "$ref": "#/responses/repoArchivedError" + } + } + } + }, + "/{username}/{repo}/projects/{id}/{column-id}/default": { + "post": { + "tags": [ + "project" + ], + "summary": "Set default column for issues/pulls", + "operationId": "setDefaultProjectColumn", + "parameters": [ + { + "type": "string", + "description": "owner of the project", + "name": "username", + "in": "path", + "required": true + }, + { + "type": "string", + "description": "repository name. If left '-', the column will be set as default for the user's project", + "name": "repo", + "in": "path", + "required": true + }, + { + "type": "integer", + "description": "project ID", + "name": "id", + "in": "path", + "required": true + }, + { + "type": "integer", + "description": "column ID", + "name": "column-id", + "in": "path", + "required": true + } + ], + "responses": { + "204": { + "$ref": "#/responses/empty" + }, + "403": { + "$ref": "#/responses/forbidden" + }, + "404": { + "$ref": "#/responses/notFound" + }, + "423": { + "$ref": "#/responses/repoArchivedError" + } + } + } + }, + "/{username}/{repo}/projects/{id}/{column-id}/move": { + "post": { + "consumes": [ + "application/json" + ], + "tags": [ + "project" + ], + "summary": "Move issues in a column", + "operationId": "moveIssues", + "parameters": [ + { + "type": "string", + "description": "owner of the project", + "name": "username", + "in": "path", + "required": true + }, + { + "type": "string", + "description": "repository name.", + "name": "repo", + "in": "path", + "required": true + }, + { + "type": "integer", + "description": "project ID", + "name": "id", + "in": "path", + "required": true + }, + { + "type": "integer", + "description": "column ID", + "name": "column-id", + "in": "path", + "required": true + }, + { + "description": "issues data", + "name": "body", + "in": "body", + "required": true, + "schema": { + "$ref": "#/definitions/MovedIssuesOption" + } + } + ], + "responses": { + "204": { + "$ref": "#/responses/empty" + }, + "403": { + "$ref": "#/responses/forbidden" + }, + "404": { + "$ref": "#/responses/notFound" + }, + "423": { + "$ref": "#/responses/repoArchivedError" + } + } + } + }, + "/{username}/{repo}/{type}/projects": { + "post": { + "consumes": [ + "application/json" + ], + "tags": [ + "project" + ], + "summary": "Change an issue's project", + "operationId": "updateIssueProject", + "parameters": [ + { + "type": "string", + "description": "owner of the project", + "name": "username", + "in": "path", + "required": true + }, + { + "type": "string", + "description": "repository name.", + "name": "repo", + "in": "path", + "required": true + }, + { + "enum": [ + "issues", + "pulls" + ], + "type": "string", + "description": "issue type (issues or pulls)", + "name": "type", + "in": "path", + "required": true + }, + { + "description": "issues data", + "name": "body", + "in": "body", + "required": true, + "schema": { + "$ref": "#/definitions/UpdateIssuesOption" + } + } + ], + "responses": { + "204": { + "$ref": "#/responses/empty" + }, + "403": { + "$ref": "#/responses/forbidden" + }, + "404": { + "$ref": "#/responses/notFound" + }, + "423": { + "$ref": "#/responses/repoArchivedError" + } + } + } } }, "definitions": { @@ -18962,6 +19693,26 @@ }, "x-go-package": "code.gitea.io/gitea/modules/structs" }, + "Column": { + "description": "Column represents a project column", + "type": "object", + "properties": { + "color": { + "type": "string", + "x-go-name": "Color" + }, + "id": { + "type": "integer", + "format": "int64", + "x-go-name": "ID" + }, + "title": { + "type": "string", + "x-go-name": "Title" + } + }, + "x-go-package": "code.gitea.io/gitea/modules/structs" + }, "CombinedStatus": { "description": "CombinedStatus holds the combined state of several statuses for a single commit", "type": "object", @@ -19942,6 +20693,54 @@ }, "x-go-package": "code.gitea.io/gitea/modules/structs" }, + "CreateProjectColumnOption": { + "description": "CreateProjectColumnOption options for creating a project column", + "type": "object", + "required": [ + "Title" + ], + "properties": { + "Color": { + "type": "string" + }, + "Sorting": { + "type": "integer", + "format": "int8" + }, + "Title": { + "type": "string" + } + }, + "x-go-package": "code.gitea.io/gitea/modules/structs" + }, + "CreateProjectOption": { + "description": "CreateProjectOption options for creating a project", + "type": "object", + "required": [ + "title" + ], + "properties": { + "card_type": { + "type": "integer", + "format": "uint8", + "x-go-name": "CardType" + }, + "content": { + "type": "string", + "x-go-name": "Content" + }, + "template_type": { + "type": "integer", + "format": "uint8", + "x-go-name": "TemplateType" + }, + "title": { + "type": "string", + "x-go-name": "Title" + } + }, + "x-go-package": "code.gitea.io/gitea/modules/structs" + }, "CreatePullRequestOption": { "description": "CreatePullRequestOption options when creating a pull request", "type": "object", @@ -20936,6 +21735,23 @@ }, "x-go-package": "code.gitea.io/gitea/modules/structs" }, + "EditProjectColumnOption": { + "description": "EditProjectColumnOption options for editing a project column", + "type": "object", + "properties": { + "Color": { + "type": "string" + }, + "Sorting": { + "type": "integer", + "format": "int8" + }, + "Title": { + "type": "string" + } + }, + "x-go-package": "code.gitea.io/gitea/modules/structs" + }, "EditPullRequestOption": { "description": "EditPullRequestOption options when modify pull request", "type": "object", @@ -22731,6 +23547,58 @@ }, "x-go-package": "code.gitea.io/gitea/modules/structs" }, + "MovedColumnsOption": { + "description": "MoveColumnsOption options for moving columns", + "type": "object", + "properties": { + "columns": { + "type": "array", + "items": { + "type": "object", + "properties": { + "columnID": { + "type": "integer", + "format": "int64", + "x-go-name": "ColumnID" + }, + "sorting": { + "type": "integer", + "format": "int64", + "x-go-name": "Sorting" + } + } + }, + "x-go-name": "Columns" + } + }, + "x-go-package": "code.gitea.io/gitea/modules/structs" + }, + "MovedIssuesOption": { + "description": "MoveIssuesOption options for moving issues", + "type": "object", + "properties": { + "issues": { + "type": "array", + "items": { + "type": "object", + "properties": { + "issueID": { + "type": "integer", + "format": "int64", + "x-go-name": "IssueID" + }, + "sorting": { + "type": "integer", + "format": "int64", + "x-go-name": "Sorting" + } + } + }, + "x-go-name": "Issues" + } + }, + "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", @@ -23312,6 +24180,75 @@ }, "x-go-package": "code.gitea.io/gitea/modules/structs" }, + "Project": { + "description": "Project represents a project", + "type": "object", + "properties": { + "card_type": { + "type": "integer", + "format": "uint8", + "x-go-name": "CardType" + }, + "closed_date_unix": { + "type": "integer", + "format": "int64", + "x-go-name": "ClosedDateUnix" + }, + "created_unix": { + "type": "integer", + "format": "int64", + "x-go-name": "CreatedUnix" + }, + "creator_id": { + "type": "integer", + "format": "int64", + "x-go-name": "CreatorID" + }, + "description": { + "type": "string", + "x-go-name": "Description" + }, + "id": { + "type": "integer", + "format": "int64", + "x-go-name": "ID" + }, + "is_closed": { + "type": "boolean", + "x-go-name": "IsClosed" + }, + "owner_id": { + "type": "integer", + "format": "int64", + "x-go-name": "OwnerID" + }, + "repo_id": { + "type": "integer", + "format": "int64", + "x-go-name": "RepoID" + }, + "template_type": { + "type": "integer", + "format": "uint8", + "x-go-name": "TemplateType" + }, + "title": { + "type": "string", + "x-go-name": "Title" + }, + "type": { + "type": "integer", + "format": "uint8", + "x-go-name": "Type" + }, + "updated_unix": { + "type": "integer", + "format": "int64", + "x-go-name": "UpdatedUnix" + } + }, + "x-go-package": "code.gitea.io/gitea/modules/structs" + }, "PublicKey": { "description": "PublicKey publickey is a user key to push code to repository", "type": "object", @@ -24786,6 +25723,26 @@ }, "x-go-package": "code.gitea.io/gitea/modules/structs" }, + "UpdateIssuesOption": { + "description": "UpdateIssuesOption options for updating issues", + "type": "object", + "properties": { + "issues": { + "type": "array", + "items": { + "type": "integer", + "format": "int64" + }, + "x-go-name": "Issues" + }, + "project_id": { + "type": "integer", + "format": "int64", + "x-go-name": "ProjectID" + } + }, + "x-go-package": "code.gitea.io/gitea/modules/structs" + }, "UpdateRepoAvatarOption": { "description": "UpdateRepoAvatarUserOption options when updating the repo avatar", "type": "object", @@ -25338,6 +26295,12 @@ } } }, + "Column": { + "description": "Column", + "schema": { + "$ref": "#/definitions/Column" + } + }, "CombinedStatus": { "description": "CombinedStatus", "schema": { @@ -25797,6 +26760,21 @@ } } }, + "Project": { + "description": "Project", + "schema": { + "$ref": "#/definitions/Project" + } + }, + "ProjectList": { + "description": "ProjectList", + "schema": { + "type": "array", + "items": { + "$ref": "#/definitions/Project" + } + } + }, "PublicKey": { "description": "PublicKey", "schema": { @@ -26222,7 +27200,7 @@ "parameterBodies": { "description": "parameterBodies", "schema": { - "$ref": "#/definitions/UpdateVariableOption" + "$ref": "#/definitions/UpdateIssuesOption" } }, "redirect": {