luckyimnotanigger/forgejo
1
0
Fork 0
mirror of https://codeberg.org/forgejo/forgejo.git synced 2025-06-01 04:12:10 +00:00
Code Issues Projects Releases Packages Wiki Activity Actions 8

Update swagger documentation (#2899)

Browse source 
* Update swagger documentation

Add docs for missing endpoints
Add documentation for request parameters
Make parameter naming consistent
Fix response documentation

* Restore delete comments
This commit is contained in:
Ethan Koenig 2017-11-12 23:02:25 -08:00 • committed by Lauris BH
parent 4287d100b3
commit f26f4a7e01
72 changed files with 8875 additions and 2323 deletions
Download patch file Download diff file Expand all files Collapse all files

45
routers/api/v1/repo/branch.go
View file

@ -13,8 +13,31 @@ import (
)
// GetBranch get a branch of a repository
// see https://github.com/gogits/go-gogs-client/wiki/Repositories#get-branch
func GetBranch(ctx *context.APIContext) {
// swagger:operation GET /repos/{owner}/{repo}/branches/{branch} repository repoGetBranch
// ---
// summary: List a repository's branches
// produces:
// - application/json
// parameters:
// - name: owner
// in: path
// description: owner of the repo
// type: string
// required: true
// - name: repo
// in: path
// description: name of the repo
// type: string
// required: true
// - name: branch
// in: path
// description: branch to get
// type: string
// required: true
// responses:
// "200":
// "$ref": "#/responses/Branch"
if ctx.Repo.TreePath != "" {
// if TreePath != "", then URL contained extra slashes
// (i.e. "master/subbranch" instead of "master"), so branch does
@ -42,8 +65,26 @@ func GetBranch(ctx *context.APIContext) {
}
// ListBranches list all the branches of a repository
// see https://github.com/gogits/go-gogs-client/wiki/Repositories#list-branches
func ListBranches(ctx *context.APIContext) {
// swagger:operation GET /repos/{owner}/{repo}/branches repository repoListBranches
// ---
// summary: List a repository's branches
// produces:
// - application/json
// parameters:
// - name: owner
// in: path
// description: owner of the repo
// type: string
// required: true
// - name: repo
// in: path
// description: name of the repo
// type: string
// required: true
// responses:
// "200":
// "$ref": "#/responses/BranchList"
branches, err := ctx.Repo.Repository.GetBranches()
if err != nil {
ctx.Error(500, "GetBranches", err)

99
routers/api/v1/repo/collaborators.go
View file

@ -13,6 +13,25 @@ import (
// ListCollaborators list a repository's collaborators
func ListCollaborators(ctx *context.APIContext) {
// swagger:operation GET /repos/{owner}/{repo}/collaborators repository repoListCollaborators
// ---
// summary: List a repository's collaborators
// produces:
// - application/json
// parameters:
// - name: owner
// in: path
// description: owner of the repo
// type: string
// required: true
// - name: repo
// in: path
// description: name of the repo
// type: string
// required: true
// responses:
// "200":
// "$ref": "#/responses/UserList"
if !ctx.Repo.IsWriter() {
ctx.Error(403, "", "User does not have push access")
return
@ -31,6 +50,32 @@ func ListCollaborators(ctx *context.APIContext) {
// IsCollaborator check if a user is a collaborator of a repository
func IsCollaborator(ctx *context.APIContext) {
// swagger:operation GET /repos/{owner}/{repo}/collaborators/{collaborator} repository repoCheckCollaborator
// ---
// summary: Check if a user is a collaborator of a repository
// produces:
// - application/json
// parameters:
// - name: owner
// in: path
// description: owner of the repo
// type: string
// required: true
// - name: repo
// in: path
// description: name of the repo
// type: string
// required: true
// - name: collaborator
// in: path
// description: username of the collaborator
// type: string
// required: true
// responses:
// "204":
// "$ref": "#/responses/empty"
// "404":
// "$ref": "#/responses/empty"
if !ctx.Repo.IsWriter() {
ctx.Error(403, "", "User does not have push access")
return
@ -56,8 +101,36 @@ func IsCollaborator(ctx *context.APIContext) {
}
}
// AddCollaborator add a collaborator of a repository
// AddCollaborator add a collaborator to a repository
func AddCollaborator(ctx *context.APIContext, form api.AddCollaboratorOption) {
// swagger:operation PUT /repos/{owner}/{repo}/collaborators/{collaborator} repository repoAddCollaborator
// ---
// summary: Add a collaborator to a repository
// produces:
// - application/json
// parameters:
// - name: owner
// in: path
// description: owner of the repo
// type: string
// required: true
// - name: repo
// in: path
// description: name of the repo
// type: string
// required: true
// - name: collaborator
// in: path
// description: username of the collaborator to add
// type: string
// required: true
// - name: body
// in: body
// schema:
// "$ref": "#/definitions/AddCollaboratorOption"
// responses:
// "204":
// "$ref": "#/responses/empty"
if !ctx.Repo.IsWriter() {
ctx.Error(403, "", "User does not have push access")
return
@ -89,6 +162,30 @@ func AddCollaborator(ctx *context.APIContext, form api.AddCollaboratorOption) {
// DeleteCollaborator delete a collaborator from a repository
func DeleteCollaborator(ctx *context.APIContext) {
// swagger:operation DELETE /repos/{owner}/{repo}/collaborators/{collaborator} repository repoDeleteCollaborator
// ---
// summary: Delete a collaborator from a repository
// produces:
// - application/json
// parameters:
// - name: owner
// in: path
// description: owner of the repo
// type: string
// required: true
// - name: repo
// in: path
// description: name of the repo
// type: string
// required: true
// - name: collaborator
// in: path
// description: username of the collaborator to delete
// type: string
// required: true
// responses:
// "204":
// "$ref": "#/responses/empty"
if !ctx.Repo.IsWriter() {
ctx.Error(403, "", "User does not have push access")
return

71
routers/api/v1/repo/file.go
View file

@ -13,8 +13,30 @@ import (
)
// GetRawFile get a file by path on a repository
// see https://github.com/gogits/go-gogs-client/wiki/Repositories-Contents#download-raw-content
func GetRawFile(ctx *context.APIContext) {
// swagger:operation GET /repos/{owner}/{repo}/raw/{filepath} repository repoGetRawFile
// ---
// summary: Get a file from a repository
// produces:
// - application/json
// parameters:
// - name: owner
// in: path
// description: owner of the repo
// type: string
// required: true
// - name: repo
// in: path
// description: name of the repo
// type: string
// required: true
// - name: filepath
// in: path
// description: filepath of the file to get
// type: string
// required: true
// responses:
// 200:
if !ctx.Repo.HasAccess() {
ctx.Status(404)
return
@ -40,8 +62,30 @@ func GetRawFile(ctx *context.APIContext) {
}
// GetArchive get archive of a repository
// see https://github.com/gogits/go-gogs-client/wiki/Repositories-Contents#download-archive
func GetArchive(ctx *context.APIContext) {
// swagger:operation GET /repos/{owner}/{repo}/archive/{filepath} repository repoGetArchive
// ---
// summary: Get an archive of a repository
// produces:
// - application/json
// parameters:
// - name: owner
// in: path
// description: owner of the repo
// type: string
// required: true
// - name: repo
// in: path
// description: name of the repo
// type: string
// required: true
// - name: archive
// in: path
// description: archive to download, consisting of a git reference and archive
// type: string
// required: true
// responses:
// 200:
repoPath := models.RepoPath(ctx.Params(":username"), ctx.Params(":reponame"))
gitRepo, err := git.OpenRepository(repoPath)
if err != nil {
@ -55,6 +99,29 @@ func GetArchive(ctx *context.APIContext) {
// GetEditorconfig get editor config of a repository
func GetEditorconfig(ctx *context.APIContext) {
// swagger:operation GET /repos/{owner}/{repo}/editorconfig/{filepath} repository repoGetEditorConfig
// ---
// summary: Get the EditorConfig definitions of a file in a repository
// produces:
// - application/json
// parameters:
// - name: owner
// in: path
// description: owner of the repo
// type: string
// required: true
// - name: repo
// in: path
// description: name of the repo
// type: string
// required: true
// - name: filepath
// in: path
// description: filepath of file to get
// type: string
// required: true
// responses:
// 200:
ec, err := ctx.Repo.GetEditorconfig()
if err != nil {
if git.IsErrNotExist(err) {

62
routers/api/v1/repo/fork.go
View file

@ -14,15 +14,25 @@ import (
// ListForks list a repository's forks
func ListForks(ctx *context.APIContext) {
// swagger:route GET /repos/{owner}/{repo}/forks repository listForks
//
// Produces:
// - application/json
//
// Responses:
// 200: RepositoryList
// 500: error
// swagger:operation GET /repos/{owner}/{repo}/forks repository listForks
// ---
// summary: List a repository's forks
// produces:
// - application/json
// parameters:
// - name: owner
// in: path
// description: owner of the repo
// type: string
// required: true
// - name: repo
// in: path
// description: name of the repo
// type: string
// required: true
// responses:
// "200":
// "$ref": "#/responses/RepositoryList"
forks, err := ctx.Repo.Repository.GetForks()
if err != nil {
ctx.Error(500, "GetForks", err)
@ -42,17 +52,29 @@ func ListForks(ctx *context.APIContext) {
// CreateFork create a fork of a repo
func CreateFork(ctx *context.APIContext, form api.CreateForkOption) {
// swagger:route POST /repos/{owner}/{repo}/forks repository createFork
//
// Produces:
// - application/json
//
// Responses:
// 202: Repository
// 403: forbidden
// 422: validationError
// 500: error
// swagger:operation POST /repos/{owner}/{repo}/forks repository createFork
// ---
// summary: Fork a repository
// produces:
// - application/json
// parameters:
// - name: owner
// in: path
// description: owner of the repo to fork
// type: string
// required: true
// - name: repo
// in: path
// description: name of the repo to fork
// type: string
// required: true
// - name: body
// in: body
// schema:
// "$ref": "#/definitions/CreateForkOption"
// responses:
// "202":
// "$ref": "#/responses/Repository"
repo := ctx.Repo.Repository
var forker *models.User // user/org that will own the fork
if form.Organization == nil {

159
routers/api/v1/repo/hook.go
View file

@ -15,15 +15,25 @@ import (
// ListHooks list all hooks of a repository
func ListHooks(ctx *context.APIContext) {
// swagger:route GET /repos/{username}/{reponame}/hooks repository repoListHooks
//
// Produces:
// - application/json
//
// Responses:
// 200: HookList
// 500: error
// swagger:operation GET /repos/{owner}/{repo}/hooks repository repoListHooks
// ---
// summary: List the hooks in a repository
// produces:
// - application/json
// parameters:
// - name: owner
// in: path
// description: owner of the repo
// type: string
// required: true
// - name: repo
// in: path
// description: name of the repo
// type: string
// required: true
// responses:
// "200":
// "$ref": "#/responses/HookList"
hooks, err := models.GetWebhooksByRepoID(ctx.Repo.Repository.ID)
if err != nil {
ctx.Error(500, "GetWebhooksByRepoID", err)
@ -39,6 +49,30 @@ func ListHooks(ctx *context.APIContext) {
// GetHook get a repo's hook by id
func GetHook(ctx *context.APIContext) {
// swagger:operation GET /repos/{owner}/{repo}/hooks/{id} repository repoGetHook
// ---
// summary: Get a hook
// produces:
// - application/json
// parameters:
// - name: owner
// in: path
// description: owner of the repo
// type: string
// required: true
// - name: repo
// in: path
// description: name of the repo
// type: string
// required: true
// - name: id
// in: path
// description: id of the hook to get
// type: integer
// required: true
// responses:
// "200":
// "$ref": "#/responses/Hook"
repo := ctx.Repo
hookID := ctx.ParamsInt64(":id")
hook, err := utils.GetRepoHook(ctx, repo.Repository.ID, hookID)
@ -50,19 +84,31 @@ func GetHook(ctx *context.APIContext) {
// CreateHook create a hook for a repository
func CreateHook(ctx *context.APIContext, form api.CreateHookOption) {
// swagger:route POST /repos/{username}/{reponame}/hooks repository repoCreateHook
//
// Consumes:
// - application/json
//
// Produces:
// - application/json
//
// Responses:
// 200: Hook
// 422: validationError
// 500: error
// swagger:operation POST /repos/{owner}/{repo}/hooks repository repoCreateHook
// ---
// summary: Create a hook
// consumes:
// - application/json
// produces:
// - application/json
// parameters:
// - name: owner
// in: path
// description: owner of the repo
// type: string
// required: true
// - name: repo
// in: path
// description: name of the repo
// type: string
// required: true
// - name: body
// in: body
// schema:
// "$ref": "#/definitions/CreateHookOption"
// responses:
// "200":
// "$ref": "#/responses/Hook"
if !utils.CheckCreateHookOption(ctx, &form) {
return
}
@ -71,32 +117,61 @@ func CreateHook(ctx *context.APIContext, form api.CreateHookOption) {
// EditHook modify a hook of a repository
func EditHook(ctx *context.APIContext, form api.EditHookOption) {
// swagger:route PATCH /repos/{username}/{reponame}/hooks/{id} repository repoEditHook
//
// Produces:
// - application/json
//
// Responses:
// 200: Hook
// 422: validationError
// 500: error
// swagger:operation PATCH /repos/{owner}/{repo}/hooks/{id} repository repoEditHook
// ---
// summary: Edit a hook in a repository
// produces:
// - application/json
// parameters:
// - name: owner
// in: path
// description: owner of the repo
// type: string
// required: true
// - name: repo
// in: path
// description: name of the repo
// type: string
// required: true
// - name: body
// in: body
// schema:
// "$ref": "#/definitions/EditHookOption"
// responses:
// "200":
// "$ref": "#/responses/Hook"
hookID := ctx.ParamsInt64(":id")
utils.EditRepoHook(ctx, &form, hookID)
}
// DeleteHook delete a hook of a repository
func DeleteHook(ctx *context.APIContext) {
// swagger:route DELETE /repos/{username}/{reponame}/hooks/{id} repository repoDeleteHook
//
// Produces:
// - application/json
//
// Responses:
// 204: empty
// 404: notFound
// 500: error
// swagger:operation DELETE /repos/{user}/{repo}/hooks/{id} repository repoDeleteHook
// ---
// summary: Delete a hook in a repository
// produces:
// - application/json
// parameters:
// - name: owner
// in: path
// description: owner of the repo
// type: string
// required: true
// - name: repo
// in: path
// description: name of the repo
// type: string
// required: true
// - name: id
// in: path
// description: id of the hook to delete
// type: integer
// required: true
// responses:
// "204":
// "$ref": "#/responses/empty"
// "404":
// "$ref": "#/responses/notFound"
if err := models.DeleteWebhookByRepoID(ctx.Repo.Repository.ID, ctx.ParamsInt64(":id")); err != nil {
if models.IsErrWebhookNotExist(err) {
ctx.Status(404)

106
routers/api/v1/repo/issue.go
View file

@ -18,6 +18,33 @@ import (
// ListIssues list the issues of a repository
func ListIssues(ctx *context.APIContext) {
// swagger:operation GET /repos/{owner}/{repo}/issues issue issueListIssues
// ---
// summary: List a repository's issues
// produces:
// - application/json
// parameters:
// - name: owner
// in: path
// description: owner of the repo
// type: string
// required: true
// - name: repo
// in: path
// description: name of the repo
// type: string
// required: true
// - name: state
// in: query
// description: whether issue is open or closed
// type: string
// - name: page
// in: query
// description: page number of requested issues
// type: integer
// responses:
// "200":
// "$ref": "#/responses/IssueList"
var isClosed util.OptionalBool
switch ctx.Query("state") {
case "closed":
@ -50,6 +77,30 @@ func ListIssues(ctx *context.APIContext) {
// GetIssue get an issue of a repository
func GetIssue(ctx *context.APIContext) {
// swagger:operation GET /repos/{owner}/{repo}/issues/{id} issue issueGetIssue
// ---
// summary: Get an issue by id
// produces:
// - application/json
// parameters:
// - name: owner
// in: path
// description: owner of the repo
// type: string
// required: true
// - name: repo
// in: path
// description: name of the repo
// type: string
// required: true
// - name: id
// in: path
// description: id of the issue to get
// type: integer
// required: true
// responses:
// "200":
// "$ref": "#/responses/Issue"
issue, err := models.GetIssueByIndex(ctx.Repo.Repository.ID, ctx.ParamsInt64(":index"))
if err != nil {
if models.IsErrIssueNotExist(err) {
@ -64,6 +115,31 @@ func GetIssue(ctx *context.APIContext) {
// CreateIssue create an issue of a repository
func CreateIssue(ctx *context.APIContext, form api.CreateIssueOption) {
// swagger:operation POST /repos/{owner}/{repo}/issues issue issueCreateIssue
// ---
// summary: Create an issue
// consumes:
// - application/json
// produces:
// - application/json
// parameters:
// - name: owner
// in: path
// description: owner of the repo
// type: string
// required: true
// - name: repo
// in: path
// description: name of the repo
// type: string
// required: true
// - name: body
// in: body
// schema:
// "$ref": "#/definitions/CreateIssueOption"
// responses:
// "201":
// "$ref": "#/responses/Issue"
issue := &models.Issue{
RepoID: ctx.Repo.Repository.ID,
Title: form.Title,
@ -114,6 +190,36 @@ func CreateIssue(ctx *context.APIContext, form api.CreateIssueOption) {
// EditIssue modify an issue of a repository
func EditIssue(ctx *context.APIContext, form api.EditIssueOption) {
// swagger:operation PATCH /repos/{owner}/{repo}/issues/{id} issue issueEditIssue
// ---
// summary: Edit an issue
// consumes:
// - application/json
// produces:
// - application/json
// parameters:
// - name: owner
// in: path
// description: owner of the repo
// type: string
// required: true
// - name: repo
// in: path
// description: name of the repo
// type: string
// required: true
// - name: id
// in: path
// description: id of the issue to edit
// type: integer
// required: true
// - name: body
// in: body
// schema:
// "$ref": "#/definitions/EditIssueOption"
// responses:
// "201":
// "$ref": "#/responses/Issue"
issue, err := models.GetIssueByIndex(ctx.Repo.Repository.ID, ctx.ParamsInt64(":index"))
if err != nil {
if models.IsErrIssueNotExist(err) {

135
routers/api/v1/repo/issue_comment.go
View file

@ -15,6 +15,34 @@ import (
// ListIssueComments list all the comments of an issue
func ListIssueComments(ctx *context.APIContext) {
// swagger:operation GET /repos/{owner}/{repo}/issue/{index}/comments issue issueGetComments
// ---
// summary: List all comments on an issue
// produces:
// - application/json
// parameters:
// - name: owner
// in: path
// description: owner of the repo
// type: string
// required: true
// - name: repo
// in: path
// description: name of the repo
// type: string
// required: true
// - name: id
// in: path
// description: index of the issue
// type: integer
// required: true
// - name: string
// in: query
// description: if provided, only comments updated since the specified time are returned.
// type: string
// responses:
// "200":
// "$ref": "#/responses/CommentList"
var since time.Time
if len(ctx.Query("since")) > 0 {
since, _ = time.Parse(time.RFC3339, ctx.Query("since"))
@ -44,8 +72,31 @@ func ListIssueComments(ctx *context.APIContext) {
ctx.JSON(200, &apiComments)
}
// ListRepoIssueComments returns all issue-comments for an issue
// ListRepoIssueComments returns all issue-comments for a repo
func ListRepoIssueComments(ctx *context.APIContext) {
// swagger:operation GET /repos/{owner}/{repo}/issues/comments issue issueGetRepoComments
// ---
// summary: List all comments in a repository
// produces:
// - application/json
// parameters:
// - name: owner
// in: path
// description: owner of the repo
// type: string
// required: true
// - name: repo
// in: path
// description: name of the repo
// type: string
// required: true
// - name: string
// in: query
// description: if provided, only comments updated since the provided time are returned.
// type: string
// responses:
// "200":
// "$ref": "#/responses/CommentList"
var since time.Time
if len(ctx.Query("since")) > 0 {
since, _ = time.Parse(time.RFC3339, ctx.Query("since"))
@ -70,6 +121,36 @@ func ListRepoIssueComments(ctx *context.APIContext) {
// CreateIssueComment create a comment for an issue
func CreateIssueComment(ctx *context.APIContext, form api.CreateIssueCommentOption) {
// swagger:operation POST /repos/{owner}/{repo}/issues/{index}/comments issue issueCreateComment
// ---
// summary: Add a comment to an issue
// consumes:
// - application/json
// produces:
// - application/json
// parameters:
// - name: owner
// in: path
// description: owner of the repo
// type: string
// required: true
// - name: repo
// in: path
// description: name of the repo
// type: string
// required: true
// - name: id
// in: path
// description: index of the issue
// type: integer
// required: true
// - name: body
// in: body
// schema:
// "$ref": "#/definitions/CreateIssueOption"
// responses:
// "201":
// "$ref": "#/responses/Comment"
issue, err := models.GetIssueByIndex(ctx.Repo.Repository.ID, ctx.ParamsInt64(":index"))
if err != nil {
ctx.Error(500, "GetIssueByIndex", err)
@ -87,6 +168,36 @@ func CreateIssueComment(ctx *context.APIContext, form api.CreateIssueCommentOpti
// EditIssueComment modify a comment of an issue
func EditIssueComment(ctx *context.APIContext, form api.EditIssueCommentOption) {
// swagger:operation PATCH /repos/{owner}/{repo}/comments/{id} issue issueEditComment
// ---
// summary: Edit a comment
// consumes:
// - application/json
// produces:
// - application/json
// parameters:
// - name: owner
// in: path
// description: owner of the repo
// type: string
// required: true
// - name: repo
// in: path
// description: name of the repo
// type: string
// required: true
// - name: id
// in: path
// description: id of the comment to edit
// type: integer
// required: true
// - name: body
// in: body
// schema:
// "$ref": "#/definitions/EditIssueCommentOption"
// responses:
// "200":
// "$ref": "#/responses/Comment"
comment, err := models.GetCommentByID(ctx.ParamsInt64(":id"))
if err != nil {
if models.IsErrCommentNotExist(err) {
@ -115,6 +226,28 @@ func EditIssueComment(ctx *context.APIContext, form api.EditIssueCommentOption)
// DeleteIssueComment delete a comment from an issue
func DeleteIssueComment(ctx *context.APIContext) {
// swagger:operation DELETE /repos/{owner}/{repo}/comments/{id} issue issueDeleteComment
// ---
// summary: Delete a comment
// parameters:
// - name: owner
// in: path
// description: owner of the repo
// type: string
// required: true
// - name: repo
// in: path
// description: name of the repo
// type: string
// required: true
// - name: id
// in: path
// description: id of comment to delete
// type: integer
// required: true
// responses:
// "204":
// "$ref": "#/responses/empty"
comment, err := models.GetCommentByID(ctx.ParamsInt64(":id"))
if err != nil {
if models.IsErrCommentNotExist(err) {

139
routers/api/v1/repo/issue_label.go
View file

@ -13,6 +13,32 @@ import (
// ListIssueLabels list all the labels of an issue
func ListIssueLabels(ctx *context.APIContext) {
// swagger:operation GET /repos/{owner}/{repo}/issues/{index}/labels issue issueGetLabels
// ---
// summary: Get an issue's labels
// produces:
// - application/json
// parameters:
// - name: owner
// in: path
// description: owner of the repo
// type: string
// required: true
// - name: repo
// in: path
// description: name of the repo
// type: string
// required: true
// - name: index
// in: path
// description: index of the issue
// type: integer
// required: true
// responses:
// "200":
// "$ref": "#/responses/LabelList"
// "404":
// "$ref": "#/responses/notFound"
issue, err := models.GetIssueByIndex(ctx.Repo.Repository.ID, ctx.ParamsInt64(":index"))
if err != nil {
if models.IsErrIssueNotExist(err) {
@ -32,6 +58,36 @@ func ListIssueLabels(ctx *context.APIContext) {
// AddIssueLabels add labels for an issue
func AddIssueLabels(ctx *context.APIContext, form api.IssueLabelsOption) {
// swagger:operation POST /repos/{owner}/{repo}/issue/{index}/labels issue issueAddLabel
// ---
// summary: Add a label to an issue
// consumes:
// - application/json
// produces:
// - application/json
// parameters:
// - name: owner
// in: path
// description: owner of the repo
// type: string
// required: true
// - name: repo
// in: path
// description: name of the repo
// type: string
// required: true
// - name: index
// in: path
// description: index of the issue
// type: integer
// required: true
// - name: body
// in: body
// schema:
// "$ref": "#/definitions/IssueLabelsOption"
// responses:
// "200":
// "$ref": "#/responses/LabelList"
if !ctx.Repo.IsWriter() {
ctx.Status(403)
return
@ -73,6 +129,35 @@ func AddIssueLabels(ctx *context.APIContext, form api.IssueLabelsOption) {
// DeleteIssueLabel delete a label for an issue
func DeleteIssueLabel(ctx *context.APIContext) {
// swagger:operation DELETE /repos/{owner}/{repo}/issue/{index}/labels/{id} issue issueRemoveLabel
// ---
// summary: Remove a label from an issue
// produces:
// - application/json
// parameters:
// - name: owner
// in: path
// description: owner of the repo
// type: string
// required: true
// - name: repo
// in: path
// description: name of the repo
// type: string
// required: true
// - name: index
// in: path
// description: index of the issue
// type: integer
// required: true
// - name: id
// in: path
// description: id of the label to remove
// type: integer
// required: true
// responses:
// "204":
// "$ref": "#/responses/empty"
if !ctx.Repo.IsWriter() {
ctx.Status(403)
return
@ -108,6 +193,36 @@ func DeleteIssueLabel(ctx *context.APIContext) {
// ReplaceIssueLabels replace labels for an issue
func ReplaceIssueLabels(ctx *context.APIContext, form api.IssueLabelsOption) {
// swagger:operation PUT /repos/{owner}/{repo}/issue/{index}/labels issue issueReplaceLabels
// ---
// summary: Replace an issue's labels
// consumes:
// - application/json
// produces:
// - application/json
// parameters:
// - name: owner
// in: path
// description: owner of the repo
// type: string
// required: true
// - name: repo
// in: path
// description: name of the repo
// type: string
// required: true
// - name: index
// in: path
// description: index of the issue
// type: integer
// required: true
// - name: body
// in: body
// schema:
// "$ref": "#/definitions/IssueLabelsOption"
// responses:
// "200":
// "$ref": "#/responses/LabelList"
if !ctx.Repo.IsWriter() {
ctx.Status(403)
return
@ -149,6 +264,30 @@ func ReplaceIssueLabels(ctx *context.APIContext, form api.IssueLabelsOption) {
// ClearIssueLabels delete all the labels for an issue
func ClearIssueLabels(ctx *context.APIContext) {
// swagger:operation DELETE /repos/{owner}/{repo}/issue/{index}/labels issue issueClearLabels
// ---
// summary: Remove all labels from an issue
// produces:
// - application/json
// parameters:
// - name: owner
// in: path
// description: owner of the repo
// type: string
// required: true
// - name: repo
// in: path
// description: name of the repo
// type: string
// required: true
// - name: index
// in: path
// description: index of the issue
// type: integer
// required: true
// responses:
// "204":
// "$ref": "#/responses/empty"
if !ctx.Repo.IsWriter() {
ctx.Status(403)
return

158
routers/api/v1/repo/issue_tracked_time.go
View file

@ -20,15 +20,30 @@ func trackedTimesToAPIFormat(trackedTimes []*models.TrackedTime) []*api.TrackedT
// ListTrackedTimes list all the tracked times of an issue
func ListTrackedTimes(ctx *context.APIContext) {
// swagger:route GET /repos/{username}/{reponame}/issues/{issue}/times repository issueTrackedTimes
//
// Produces:
// - application/json
//
// Responses:
// 200: TrackedTimes
// 404: error
// 500: error
// swagger:operation GET /repos/{owner}/{repo}/issues/{index}/times issue issueTrackedTimes
// ---
// summary: List an issue's tracked times
// produces:
// - application/json
// parameters:
// - name: owner
// in: path
// description: owner of the repo
// type: string
// required: true
// - name: repo
// in: path
// description: name of the repo
// type: string
// required: true
// - name: repo
// in: path
// description: index of the issue
// type: integer
// required: true
// responses:
// "200":
// "$ref": "#/responses/TrackedTimeList"
if !ctx.Repo.Repository.IsTimetrackerEnabled() {
ctx.Error(404, "IsTimetrackerEnabled", "Timetracker is diabled")
return
@ -54,17 +69,40 @@ func ListTrackedTimes(ctx *context.APIContext) {
// AddTime adds time manual to the given issue
func AddTime(ctx *context.APIContext, form api.AddTimeOption) {
// swagger:route Post /repos/{username}/{reponame}/issues/{issue}/times repository addTime
//
// Produces:
// - application/json
//
// Responses:
// 200: TrackedTime
// 400: error
// 403: error
// 404: error
// 500: error
// swagger:operation Post /repos/{owner}/{repo}/issues/{index}/times issue issueAddTime
// ---
// summary: Add a tracked time to a issue
// consumes:
// - application/json
// produces:
// - application/json
// parameters:
// - name: owner
// in: path
// description: owner of the repo
// type: string
// required: true
// - name: repo
// in: path
// description: name of the repo
// type: string
// required: true
// - name: id
// in: path
// description: index of the issue to add tracked time to
// type: integer
// required: true
// - name: body
// in: body
// schema:
// "$ref": "#/definitions/AddTimeOption"
// responses:
// "200":
// "$ref": "#/responses/TrackedTime"
// "400":
// "$ref": "#/responses/error"
// "403":
// "$ref": "#/responses/error"
issue, err := models.GetIssueByIndex(ctx.Repo.Repository.ID, ctx.ParamsInt64(":index"))
if err != nil {
if models.IsErrIssueNotExist(err) {
@ -93,16 +131,30 @@ func AddTime(ctx *context.APIContext, form api.AddTimeOption) {
// ListTrackedTimesByUser lists all tracked times of the user
func ListTrackedTimesByUser(ctx *context.APIContext) {
// swagger:route GET /repos/{username}/{reponame}/times/{timetrackingusername} user userTrackedTimes
//
// Produces:
// - application/json
//
// Responses:
// 200: TrackedTimes
// 400: error
// 404: error
// 500: error
// swagger:operation GET /repos/{owner}/{repo}/times/{tracker} user userTrackedTimes
// ---
// summary: List a user's tracked times in a repo
// produces:
// - application/json
// parameters:
// - name: owner
// in: path
// description: owner of the repo
// type: string
// required: true
// - name: repo
// in: path
// description: name of the repo
// type: string
// required: true
// - name: user
// in: path
// description: username of user
// type: string
// required: true
// responses:
// "200":
// "$ref": "#/responses/TrackedTimeList"
if !ctx.Repo.Repository.IsTimetrackerEnabled() {
ctx.JSON(400, struct{ Message string }{Message: "time tracking disabled"})
return
@ -131,17 +183,27 @@ func ListTrackedTimesByUser(ctx *context.APIContext) {
ctx.JSON(200, &apiTrackedTimes)
}
// ListTrackedTimesByRepository lists all tracked times of the user
// ListTrackedTimesByRepository lists all tracked times of the repository
func ListTrackedTimesByRepository(ctx *context.APIContext) {
// swagger:route GET /repos/{username}/{reponame}/times repository repoTrackedTimes
//
// Produces:
// - application/json
//
// Responses:
// 200: TrackedTimes
// 400: error
// 500: error
// swagger:operation GET /repos/{owner}/{repo}/times repository repoTrackedTimes
// ---
// summary: List a repo's tracked times
// produces:
// - application/json
// parameters:
// - name: owner
// in: path
// description: owner of the repo
// type: string
// required: true
// - name: repo
// in: path
// description: name of the repo
// type: string
// required: true
// responses:
// "200":
// "$ref": "#/responses/TrackedTimeList"
if !ctx.Repo.Repository.IsTimetrackerEnabled() {
ctx.JSON(400, struct{ Message string }{Message: "time tracking disabled"})
return
@ -158,14 +220,14 @@ func ListTrackedTimesByRepository(ctx *context.APIContext) {
// ListMyTrackedTimes lists all tracked times of the current user
func ListMyTrackedTimes(ctx *context.APIContext) {
// swagger:route GET /user/times user userTrackedTimes
//
// Produces:
// - application/json
//
// Responses:
// 200: TrackedTimes
// 500: error
// swagger:operation GET /user/times user userCurrentTrackedTimes
// ---
// summary: List the current user's tracked times
// produces:
// - application/json
// responses:
// "200":
// "$ref": "#/responses/TrackedTimeList"
trackedTimes, err := models.GetTrackedTimes(models.FindTrackedTimesOptions{UserID: ctx.User.ID})
if err != nil {
ctx.Error(500, "GetTrackedTimesByUser", err)

94
routers/api/v1/repo/key.go
View file

@ -20,8 +20,26 @@ func composeDeployKeysAPILink(repoPath string) string {
}
// ListDeployKeys list all the deploy keys of a repository
// see https://github.com/gogits/go-gogs-client/wiki/Repositories-Deploy-Keys#list-deploy-keys
func ListDeployKeys(ctx *context.APIContext) {
// swagger:operation GET /repos/{owner}/{repo}/keys repository repoListKeys
// ---
// summary: List a repository's keys
// produces:
// - application/json
// parameters:
// - name: owner
// in: path
// description: owner of the repo
// type: string
// required: true
// - name: repo
// in: path
// description: name of the repo
// type: string
// required: true
// responses:
// "200":
// "$ref": "#/responses/DeployKeyList"
keys, err := models.ListDeployKeys(ctx.Repo.Repository.ID)
if err != nil {
ctx.Error(500, "ListDeployKeys", err)
@ -42,8 +60,31 @@ func ListDeployKeys(ctx *context.APIContext) {
}
// GetDeployKey get a deploy key by id
// see https://github.com/gogits/go-gogs-client/wiki/Repositories-Deploy-Keys#get-a-deploy-key
func GetDeployKey(ctx *context.APIContext) {
// swagger:operation GET /repos/{owner}/{repo}/keys/{id} repository repoGetKey
// ---
// summary: Get a repository's key by id
// produces:
// - application/json
// parameters:
// - name: owner
// in: path
// description: owner of the repo
// type: string
// required: true
// - name: repo
// in: path
// description: name of the repo
// type: string
// required: true
// - name: id
// in: path
// description: id of the key to get
// type: integer
// required: true
// responses:
// "200":
// "$ref": "#/responses/DeployKey"
key, err := models.GetDeployKeyByID(ctx.ParamsInt64(":id"))
if err != nil {
if models.IsErrDeployKeyNotExist(err) {
@ -85,8 +126,32 @@ func HandleAddKeyError(ctx *context.APIContext, err error) {
}
// CreateDeployKey create deploy key for a repository
// see https://github.com/gogits/go-gogs-client/wiki/Repositories-Deploy-Keys#add-a-new-deploy-key
func CreateDeployKey(ctx *context.APIContext, form api.CreateKeyOption) {
// swagger:operation POST /repos/{owner}/{repo}/keys repository repoCreateKey
// ---
// summary: Add a key to a repository
// consumes:
// - application/json
// produces:
// - application/json
// parameters:
// - name: owner
// in: path
// description: owner of the repo
// type: string
// required: true
// - name: repo
// in: path
// description: name of the repo
// type: string
// required: true
// - name: body
// in: body
// schema:
// "$ref": "#/definitions/CreateKeyOption"
// responses:
// "201":
// "$ref": "#/responses/DeployKey"
content, err := models.CheckPublicKeyString(form.Key)
if err != nil {
HandleCheckKeyStringError(ctx, err)
@ -105,8 +170,29 @@ func CreateDeployKey(ctx *context.APIContext, form api.CreateKeyOption) {
}
// DeleteDeploykey delete deploy key for a repository
// see https://github.com/gogits/go-gogs-client/wiki/Repositories-Deploy-Keys#remove-a-deploy-key
func DeleteDeploykey(ctx *context.APIContext) {
// swagger:operation DELETE /repos/{owner}/{repo}/keys/{id} repository repoDeleteKey
// ---
// summary: Delete a key from a repository
// parameters:
// - name: owner
// in: path
// description: owner of the repo
// type: string
// required: true
// - name: repo
// in: path
// description: name of the repo
// type: string
// required: true
// - name: id
// in: path
// description: id of the key to delete
// type: integer
// required: true
// responses:
// "204":
// "$ref": "#/responses/empty"
if err := models.DeleteDeployKey(ctx.User, ctx.ParamsInt64(":id")); err != nil {
if models.IsErrKeyAccessDenied(err) {
ctx.Error(403, "", "You do not have access to this key")

120
routers/api/v1/repo/label.go
View file

@ -15,6 +15,25 @@ import (
// ListLabels list all the labels of a repository
func ListLabels(ctx *context.APIContext) {
// swagger:operation GET /repos/{owner}/{repo}/labels issue issueListLabels
// ---
// summary: Get all of a repository's labels
// produces:
// - application/json
// parameters:
// - name: owner
// in: path
// description: owner of the repo
// type: string
// required: true
// - name: repo
// in: path
// description: name of the repo
// type: string
// required: true
// responses:
// "200":
// "$ref": "#/responses/LabelList"
labels, err := models.GetLabelsByRepoID(ctx.Repo.Repository.ID, ctx.Query("sort"))
if err != nil {
ctx.Error(500, "GetLabelsByRepoID", err)
@ -30,6 +49,30 @@ func ListLabels(ctx *context.APIContext) {
// GetLabel get label by repository and label id
func GetLabel(ctx *context.APIContext) {
// swagger:operation GET /repos/{owner}/{repo}/labels/{id} issue issueGetLabel
// ---
// summary: Get a single label
// produces:
// - application/json
// parameters:
// - name: owner
// in: path
// description: owner of the repo
// type: string
// required: true
// - name: repo
// in: path
// description: name of the repo
// type: string
// required: true
// - name: id
// in: path
// description: id of the label to get
// type: integer
// required: true
// responses:
// "200":
// "$ref": "#/responses/Label"
var (
label *models.Label
err error
@ -54,6 +97,31 @@ func GetLabel(ctx *context.APIContext) {
// CreateLabel create a label for a repository
func CreateLabel(ctx *context.APIContext, form api.CreateLabelOption) {
// swagger:operation POST /repos/{owner}/{repo}/labels issue issueCreateLabel
// ---
// summary: Create a label
// consumes:
// - application/json
// produces:
// - application/json
// parameters:
// - name: owner
// in: path
// description: owner of the repo
// type: string
// required: true
// - name: repo
// in: path
// description: name of the repo
// type: string
// required: true
// - name: body
// in: body
// schema:
// "$ref": "#/definitions/CreateLabelOption"
// responses:
// "201":
// "$ref": "#/responses/Label"
if !ctx.Repo.IsWriter() {
ctx.Status(403)
return
@ -73,6 +141,36 @@ func CreateLabel(ctx *context.APIContext, form api.CreateLabelOption) {
// EditLabel modify a label for a repository
func EditLabel(ctx *context.APIContext, form api.EditLabelOption) {
// swagger:operation PATCH /repos/{owner}/{repo}/labels/{id} issue issueEditLabel
// ---
// summary: Update a label
// consumes:
// - application/json
// produces:
// - application/json
// parameters:
// - name: owner
// in: path
// description: owner of the repo
// type: string
// required: true
// - name: repo
// in: path
// description: name of the repo
// type: string
// required: true
// - name: id
// in: path
// description: id of the label to edit
// type: integer
// required: true
// - name: body
// in: body
// schema:
// "$ref": "#/definitions/EditLabelOption"
// responses:
// "200":
// "$ref": "#/responses/Label"
if !ctx.Repo.IsWriter() {
ctx.Status(403)
return
@ -103,6 +201,28 @@ func EditLabel(ctx *context.APIContext, form api.EditLabelOption) {
// DeleteLabel delete a label for a repository
func DeleteLabel(ctx *context.APIContext) {
// swagger:operation DELETE /repos/{owner}/{repo}/labels/{id} issue issueDeleteLabel
// ---
// summary: Delete a label
// parameters:
// - name: owner
// in: path
// description: owner of the repo
// type: string
// required: true
// - name: repo
// in: path
// description: name of the repo
// type: string
// required: true
// - name: id
// in: path
// description: id of the label to delete
// type: integer
// required: true
// responses:
// "204":
// "$ref": "#/responses/empty"
if !ctx.Repo.IsWriter() {
ctx.Status(403)
return

115
routers/api/v1/repo/milestone.go
View file

@ -15,6 +15,14 @@ import (
// ListMilestones list all the milestones for a repository
func ListMilestones(ctx *context.APIContext) {
// swagger:operation GET /repos/{owner}/{repo}/milestones/{id} issue issueGetMilestone
// ---
// summary: Get a milestone
// produces:
// - application/json
// responses:
// "200":
// "$ref": "#/responses/Milestone"
milestones, err := models.GetMilestonesByRepoID(ctx.Repo.Repository.ID)
if err != nil {
ctx.Error(500, "GetMilestonesByRepoID", err)
@ -30,6 +38,41 @@ func ListMilestones(ctx *context.APIContext) {
// GetMilestone get a milestone for a repository
func GetMilestone(ctx *context.APIContext) {
// swagger:operation GET /repos/{owner}/{repo}/milestones issue issueGetMilestones
// ---
// summary: Get all of a repository's milestones
// produces:
// - application/json
// parameters:
// - name: owner
// in: path
// description: owner of the repo
// type: string
// required: true
// - name: repo
// in: path
// description: name of the repo
// type: string
// required: true
// parameters:
// - name: owner
// in: path
// description: owner of the repo
// type: string
// required: true
// - name: repo
// in: path
// description: name of the repo
// type: string
// required: true
// - name: id
// in: path
// description: id of the milestone to get
// type: integer
// required: true
// responses:
// "200":
// "$ref": "#/responses/MilestoneList"
milestone, err := models.GetMilestoneByRepoID(ctx.Repo.Repository.ID, ctx.ParamsInt64(":id"))
if err != nil {
if models.IsErrMilestoneNotExist(err) {
@ -44,6 +87,31 @@ func GetMilestone(ctx *context.APIContext) {
// CreateMilestone create a milestone for a repository
func CreateMilestone(ctx *context.APIContext, form api.CreateMilestoneOption) {
// swagger:operation POST /repos/{owner}/{repo}/milestones issue issueCreateMilestone
// ---
// summary: Create a milestone
// consumes:
// - application/json
// produces:
// - application/json
// parameters:
// - name: owner
// in: path
// description: owner of the repo
// type: string
// required: true
// - name: repo
// in: path
// description: name of the repo
// type: string
// required: true
// - name: body
// in: body
// schema:
// "$ref": "#/definitions/CreateMilestoneOption"
// responses:
// "201":
// "$ref": "#/responses/Milestone"
if form.Deadline == nil {
defaultDeadline, _ := time.ParseInLocation("2006-01-02", "9999-12-31", time.Local)
form.Deadline = &defaultDeadline
@ -65,6 +133,31 @@ func CreateMilestone(ctx *context.APIContext, form api.CreateMilestoneOption) {
// EditMilestone modify a milestone for a repository
func EditMilestone(ctx *context.APIContext, form api.EditMilestoneOption) {
// swagger:operation PATCH /repos/{owner}/{repo}/milestones/{id} issue issueEditMilestone
// ---
// summary: Update a milestone
// consumes:
// - application/json
// produces:
// - application/json
// parameters:
// - name: owner
// in: path
// description: owner of the repo
// type: string
// required: true
// - name: repo
// in: path
// description: name of the repo
// type: string
// required: true
// - name: body
// in: body
// schema:
// "$ref": "#/definitions/EditMilestoneOption"
// responses:
// "200":
// "$ref": "#/responses/Milestone"
milestone, err := models.GetMilestoneByRepoID(ctx.Repo.Repository.ID, ctx.ParamsInt64(":id"))
if err != nil {
if models.IsErrMilestoneNotExist(err) {
@ -94,6 +187,28 @@ func EditMilestone(ctx *context.APIContext, form api.EditMilestoneOption) {
// DeleteMilestone delete a milestone for a repository
func DeleteMilestone(ctx *context.APIContext) {
// swagger:operation DELETE /repos/{owner}/{repo}/milestones/{id} issue issueDeleteMilestone
// ---
// summary: Delete a milestone
// parameters:
// - name: owner
// in: path
// description: owner of the repo
// type: string
// required: true
// - name: repo
// in: path
// description: name of the repo
// type: string
// required: true
// - name: body
// in: path
// description: id of the milestone to delete
// type: integer
// required: true
// responses:
// "204":
// "$ref": "#/responses/empty"
if err := models.DeleteMilestoneByRepoID(ctx.Repo.Repository.ID, ctx.ParamsInt64(":id")); err != nil {
ctx.Error(500, "DeleteMilestoneByRepoID", err)
return

157
routers/api/v1/repo/pull.go
View file

@ -18,6 +18,25 @@ import (
// ListPullRequests returns a list of all PRs
func ListPullRequests(ctx *context.APIContext, form api.ListPullRequestsOptions) {
// swagger:operation GET /repos/{owner}/{repo}/pulls repository repoListPullRequests
// ---
// summary: List a repo's pull requests
// produces:
// - application/json
// parameters:
// - name: owner
// in: path
// description: owner of the repo
// type: string
// required: true
// - name: repo
// in: path
// description: name of the repo
// type: string
// required: true
// responses:
// "200":
// "$ref": "#/responses/PullRequestList"
prs, maxResults, err := models.PullRequests(ctx.Repo.Repository.ID, &models.PullRequestsOptions{
Page: ctx.QueryInt("page"),
State: ctx.QueryTrim("state"),
@ -58,6 +77,30 @@ func ListPullRequests(ctx *context.APIContext, form api.ListPullRequestsOptions)
// GetPullRequest returns a single PR based on index
func GetPullRequest(ctx *context.APIContext) {
// swagger:operation GET /repos/{owner}/{repo}/pulls/{index} repository repoGetPullRequest
// ---
// summary: Get a pull request
// produces:
// - application/json
// parameters:
// - name: owner
// in: path
// description: owner of the repo
// type: string
// required: true
// - name: repo
// in: path
// description: name of the repo
// type: string
// required: true
// - name: index
// in: path
// description: index of the pull request to get
// type: integer
// required: true
// responses:
// "200":
// "$ref": "#/responses/PullRequest"
pr, err := models.GetPullRequestByIndex(ctx.Repo.Repository.ID, ctx.ParamsInt64(":index"))
if err != nil {
if models.IsErrPullRequestNotExist(err) {
@ -81,6 +124,31 @@ func GetPullRequest(ctx *context.APIContext) {
// CreatePullRequest does what it says
func CreatePullRequest(ctx *context.APIContext, form api.CreatePullRequestOption) {
// swagger:operation POST /repos/{owner}/{repo}/pulls repository repoCreatePullRequest
// ---
// summary: Create a pull request
// consumes:
// - application/json
// produces:
// - application/json
// parameters:
// - name: owner
// in: path
// description: owner of the repo
// type: string
// required: true
// - name: repo
// in: path
// description: name of the repo
// type: string
// required: true
// - name: body
// in: body
// schema:
// "$ref": "#/definitions/CreatePullRequestOption"
// responses:
// "201":
// "$ref": "#/responses/PullRequest"
var (
repo = ctx.Repo.Repository
labelIDs []int64
@ -204,6 +272,36 @@ func CreatePullRequest(ctx *context.APIContext, form api.CreatePullRequestOption
// EditPullRequest does what it says
func EditPullRequest(ctx *context.APIContext, form api.EditPullRequestOption) {
// swagger:operation PATCH /repos/{owner}/{repo}/pulls/{index} repository repoEditPullRequest
// ---
// summary: Update a pull request
// consumes:
// - application/json
// produces:
// - application/json
// parameters:
// - name: owner
// in: path
// description: owner of the repo
// type: string
// required: true
// - name: repo
// in: path
// description: name of the repo
// type: string
// required: true
// - name: index
// in: path
// description: index of the pull request to edit
// type: integer
// required: true
// - name: body
// in: body
// schema:
// "$ref": "#/definitions/EditPullRequestOption"
// responses:
// "201":
// "$ref": "#/responses/PullRequest"
pr, err := models.GetPullRequestByIndex(ctx.Repo.Repository.ID, ctx.ParamsInt64(":index"))
if err != nil {
if models.IsErrPullRequestNotExist(err) {
@ -283,13 +381,42 @@ func EditPullRequest(ctx *context.APIContext, form api.EditPullRequestOption) {
return
}
// TODO this should be 200, not 201
ctx.JSON(201, pr.APIFormat())
}
// IsPullRequestMerged checks if a PR exists given an index
// - Returns 204 if it exists
// Otherwise 404
func IsPullRequestMerged(ctx *context.APIContext) {
// swagger:operation GET /repos/{owner}/{repo}/pulls/{index}/merge repository repoPullRequestIsMerged
// ---
// summary: Check if a pull request has been merged
// produces:
// - application/json
// parameters:
// - name: owner
// in: path
// description: owner of the repo
// type: string
// required: true
// - name: repo
// in: path
// description: name of the repo
// type: string
// required: true
// - name: index
// in: path
// description: index of the pull request
// type: integer
// required: true
// responses:
// "204":
// description: pull request has been merged
// schema:
// "$ref": "#/responses/empty"
// "404":
// description: pull request has not been merged
// schema:
// "$ref": "#/responses/empty"
pr, err := models.GetPullRequestByIndex(ctx.Repo.Repository.ID, ctx.ParamsInt64(":index"))
if err != nil {
if models.IsErrPullRequestNotExist(err) {
@ -308,6 +435,32 @@ func IsPullRequestMerged(ctx *context.APIContext) {
// MergePullRequest merges a PR given an index
func MergePullRequest(ctx *context.APIContext) {
// swagger:operation POST /repos/{owner}/{repo}/pulls/{index}/merge repository repoMergePullRequest
// ---
// summary: Merge a pull request
// produces:
// - application/json
// parameters:
// - name: owner
// in: path
// description: owner of the repo
// type: string
// required: true
// - name: repo
// in: path
// description: name of the repo
// type: string
// required: true
// - name: index
// in: path
// description: index of the pull request to merge
// type: integer
// required: true
// responses:
// "200":
// "$ref": "#/responses/empty"
// "405":
// "$ref": "#/responses/empty"
pr, err := models.GetPullRequestByIndex(ctx.Repo.Repository.ID, ctx.ParamsInt64(":index"))
if err != nil {
if models.IsErrPullRequestNotExist(err) {

120
routers/api/v1/repo/release.go
View file

@ -13,6 +13,30 @@ import (
// GetRelease get a single release of a repository
func GetRelease(ctx *context.APIContext) {
// swagger:operation GET /repos/{owner}/{repo}/releases repository repoGetRelease
// ---
// summary: Get a release
// produces:
// - application/json
// parameters:
// - name: owner
// in: path
// description: owner of the repo
// type: string
// required: true
// - name: repo
// in: path
// description: name of the repo
// type: string
// required: true
// - name: repo
// in: path
// description: id of the release to get
// type: integer
// required: true
// responses:
// "200":
// "$ref": "#/responses/Release"
id := ctx.ParamsInt64(":id")
release, err := models.GetReleaseByID(id)
if err != nil {
@ -32,6 +56,25 @@ func GetRelease(ctx *context.APIContext) {
// ListReleases list a repository's releases
func ListReleases(ctx *context.APIContext) {
// swagger:operation GET /repos/{owner}/{repo}/releases repository repoListReleases
// ---
// summary: List a repo's releases
// produces:
// - application/json
// parameters:
// - name: owner
// in: path
// description: owner of the repo
// type: string
// required: true
// - name: repo
// in: path
// description: name of the repo
// type: string
// required: true
// responses:
// "200":
// "$ref": "#/responses/ReleaseList"
releases, err := models.GetReleasesByRepoID(ctx.Repo.Repository.ID, models.FindReleasesOptions{
IncludeDrafts: ctx.Repo.AccessMode >= models.AccessModeWrite,
IncludeTags: false,
@ -53,6 +96,31 @@ func ListReleases(ctx *context.APIContext) {
// CreateRelease create a release
func CreateRelease(ctx *context.APIContext, form api.CreateReleaseOption) {
// swagger:operation GET /repos/{owner}/{repo}/releases repository repoCreateRelease
// ---
// summary: Create a release
// consumes:
// - application/json
// produces:
// - application/json
// parameters:
// - name: owner
// in: path
// description: owner of the repo
// type: string
// required: true
// - name: repo
// in: path
// description: name of the repo
// type: string
// required: true
// - name: body
// in: body
// schema:
// "$ref": "#/definitions/CreateReleaseOption"
// responses:
// "201":
// "$ref": "#/responses/Release"
if ctx.Repo.AccessMode < models.AccessModeWrite {
ctx.Status(403)
return
@ -110,6 +178,36 @@ func CreateRelease(ctx *context.APIContext, form api.CreateReleaseOption) {
// EditRelease edit a release
func EditRelease(ctx *context.APIContext, form api.EditReleaseOption) {
// swagger:operation PATCH /repos/{owner}/{repo}/releases/{id} repository repoEditRelease
// ---
// summary: Update a release
// consumes:
// - application/json
// produces:
// - application/json
// parameters:
// - name: owner
// in: path
// description: owner of the repo
// type: string
// required: true
// - name: repo
// in: path
// description: name of the repo
// type: string
// required: true
// - name: id
// in: path
// description: id of the release to edit
// type: integer
// required: true
// - name: body
// in: body
// schema:
// "$ref": "#/definitions/EditReleaseOption"
// responses:
// "200":
// "$ref": "#/responses/Release"
if ctx.Repo.AccessMode < models.AccessModeWrite {
ctx.Status(403)
return
@ -163,6 +261,28 @@ func EditRelease(ctx *context.APIContext, form api.EditReleaseOption) {
// DeleteRelease delete a release from a repository
func DeleteRelease(ctx *context.APIContext) {
// swagger:operation DELETE /repos/{owner}/{repo}/releases/{id} repository repoDeleteRelease
// ---
// summary: Delete a release
// parameters:
// - name: owner
// in: path
// description: owner of the repo
// type: string
// required: true
// - name: repo
// in: path
// description: name of the repo
// type: string
// required: true
// - name: id
// in: path
// description: id of the release to delete
// type: integer
// required: true
// responses:
// "204":
// "$ref": "#/responses/empty"
if ctx.Repo.AccessMode < models.AccessModeWrite {
ctx.Status(403)
return

276
routers/api/v1/repo/repo.go
View file

@ -20,45 +20,40 @@ import (
"code.gitea.io/gitea/routers/api/v1/convert"
)
// SearchRepoOption options when searching repositories
// swagger:parameters repoSearch
type SearchRepoOption struct { // TODO: Move SearchRepoOption to Gitea SDK
// Keyword to search
//
// in: query
Keyword string `json:"q"`
// Repository owner to search
//
// in: query
OwnerID int64 `json:"uid"`
// Limit of result
//
// maximum: setting.ExplorePagingNum
// in: query
PageSize int `json:"limit"`
// Type of repository to search, related to owner
//
// in: query
SearchMode string `json:"mode"`
// Search only owners repositories
// Has effect only if owner is provided and mode is not "collaborative"
//
// in: query
OwnerExclusive bool `json:"exclusive"`
}
// Search repositories via options
func Search(ctx *context.APIContext) {
// swagger:route GET /repos/search repository repoSearch
//
// Produces:
// - application/json
//
// Responses:
// 200: SearchResults
// 422: validationError
// 500: SearchError
// swagger:operation GET /repos/search repository repoSearch
// ---
// summary: Search for repositories
// produces:
// - application/json
// parameters:
// - name: q
// in: query
// description: keyword
// type: string
// - name: uid
// in: query
// description: if provided, will return only repos owned by the user with the given id
// type: integer
// - name: limit
// in: query
// description: maximum number of repos to return
// type: integer
// - name: mode
// in: query
// description: type of repository to search for. Supported values are
// "fork", "source", "mirror" and "collaborative"
// type: string
// - name: exclusive
// in: query
// description: only search for repositories owned by the authenticated user
// type: boolean
// responses:
// "200":
// "$ref": "#/responses/SearchResults"
// "422":
// "$ref": "#/responses/validationError"
opts := &models.SearchRepoOptions{
Keyword: strings.Trim(ctx.Query("q"), " "),
OwnerID: ctx.QueryInt64("uid"),
@ -187,22 +182,23 @@ func CreateUserRepo(ctx *context.APIContext, owner *models.User, opt api.CreateR
// Create one repository of mine
func Create(ctx *context.APIContext, opt api.CreateRepoOption) {
// swagger:route POST /user/repos repository user createCurrentUserRepo
//
// Consumes:
// - application/json
//
// Produces:
// - application/json
//
// Responses:
// 201: Repository
// 403: forbidden
// 422: validationError
// 500: error
// Shouldn't reach this condition, but just in case.
// swagger:operation POST /user/repos repository user createCurrentUserRepo
// ---
// summary: Create a repository
// consumes:
// - application/json
// produces:
// - application/json
// parameters:
// - name: body
// in: body
// schema:
// "$ref": "#/definitions/CreateRepoOption"
// responses:
// "201":
// "$ref": "#/responses/Repository"
if ctx.User.IsOrganization() {
// Shouldn't reach this condition, but just in case.
ctx.Error(422, "", "not allowed creating repository for organization")
return
}
@ -211,20 +207,30 @@ func Create(ctx *context.APIContext, opt api.CreateRepoOption) {
// CreateOrgRepo create one repository of the organization
func CreateOrgRepo(ctx *context.APIContext, opt api.CreateRepoOption) {
// swagger:route POST /org/{org}/repos organization createOrgRepo
//
// Consumes:
// - application/json
//
// Produces:
// - application/json
//
// Responses:
// 201: Repository
// 422: validationError
// 403: forbidden
// 500: error
// swagger:operation POST /org/{org}/repos organization createOrgRepo
// ---
// summary: Create a repository in an organization
// consumes:
// - application/json
// produces:
// - application/json
// parameters:
// - name: org
// in: path
// description: name of organization
// type: string
// required: true
// - name: body
// in: body
// schema:
// "$ref": "#/definitions/CreateRepoOption"
// responses:
// "201":
// "$ref": "#/responses/Repository"
// "422":
// "$ref": "#/responses/validationError"
// "403":
// "$ref": "#/responses/forbidden"
org, err := models.GetOrgByName(ctx.Params(":org"))
if err != nil {
if models.IsErrOrgNotExist(err) {
@ -244,19 +250,21 @@ func CreateOrgRepo(ctx *context.APIContext, opt api.CreateRepoOption) {
// Migrate migrate remote git repository to gitea
func Migrate(ctx *context.APIContext, form auth.MigrateRepoForm) {
// swagger:route POST /repos/migrate repository repoMigrate
//
// Consumes:
// - application/json
//
// Produces:
// - application/json
//
// Responses:
// 201: Repository
// 422: validationError
// 500: error
// swagger:operation POST /repos/migrate repository repoMigrate
// ---
// summary: Migrate a remote git repository
// consumes:
// - application/json
// produces:
// - application/json
// parameters:
// - name: body
// in: body
// schema:
// "$ref": "#/definitions/MigrateRepoForm"
// responses:
// "201":
// "$ref": "#/responses/Repository"
ctxUser := ctx.User
// Not equal means context user is an organization,
// or is another user/organization if current user is admin.
@ -329,29 +337,44 @@ func Migrate(ctx *context.APIContext, form auth.MigrateRepoForm) {
// Get one repository
func Get(ctx *context.APIContext) {
// swagger:route GET /repos/{username}/{reponame} repository repoGet
//
// Produces:
// - application/json
//
// Responses:
// 200: Repository
// 500: error
// swagger:operation GET /repos/{owner}/{repo} repository repoGet
// ---
// summary: Get a repository
// produces:
// - application/json
// parameters:
// - name: owner
// in: path
// description: owner of the repo
// type: string
// required: true
// - name: repo
// in: path
// description: name of the repo
// type: string
// required: true
// responses:
// "200":
// "$ref": "#/responses/Repository"
ctx.JSON(200, ctx.Repo.Repository.APIFormat(ctx.Repo.AccessMode))
}
// GetByID returns a single Repository
func GetByID(ctx *context.APIContext) {
// swagger:route GET /repositories/{id} repository repoGetByID
//
// Produces:
// - application/json
//
// Responses:
// 200: Repository
// 500: error
// swagger:operation GET /repositories/{id} repository repoGetByID
// ---
// summary: Get a repository by id
// produces:
// - application/json
// parameters:
// - name: id
// in: path
// description: id of the repo to get
// type: integer
// required: true
// responses:
// "200":
// "$ref": "#/responses/Repository"
repo, err := models.GetRepositoryByID(ctx.ParamsInt64(":id"))
if err != nil {
if models.IsErrRepoNotExist(err) {
@ -375,16 +398,27 @@ func GetByID(ctx *context.APIContext) {
// Delete one repository
func Delete(ctx *context.APIContext) {
// swagger:route DELETE /repos/{username}/{reponame} repository repoDelete
//
// Produces:
// - application/json
//
// Responses:
// 204: empty
// 403: forbidden
// 500: error
// swagger:operation DELETE /repos/{owner}/{repo} repository repoDelete
// ---
// summary: Delete a repository
// produces:
// - application/json
// parameters:
// - name: owner
// in: path
// description: owner of the repo to delete
// type: string
// required: true
// - name: repo
// in: path
// description: name of the repo to delete
// type: string
// required: true
// responses:
// "204":
// "$ref": "#/responses/empty"
// "403":
// "$ref": "#/responses/forbidden"
if !ctx.Repo.IsAdmin() {
ctx.Error(403, "", "Must have admin rights")
return
@ -408,15 +442,25 @@ func Delete(ctx *context.APIContext) {
// MirrorSync adds a mirrored repository to the sync queue
func MirrorSync(ctx *context.APIContext) {
// swagger:route POST /repos/{username}/{reponame}/mirror-sync repository repoMirrorSync
//
// Produces:
// - application/json
//
// Responses:
// 200: empty
// 403: forbidden
// swagger:operation POST /repos/{owner}/{repo}/mirror-sync repository repoMirrorSync
// ---
// summary: Sync a mirrored repository
// produces:
// - application/json
// parameters:
// - name: owner
// in: path
// description: owner of the repo to sync
// type: string
// required: true
// - name: repo
// in: path
// description: name of the repo to sync
// type: string
// required: true
// responses:
// "200":
// "$ref": "#/responses/empty"
repo := ctx.Repo.Repository
if !ctx.Repo.IsWriter() {

19
routers/api/v1/repo/star.go
View file

@ -12,6 +12,25 @@ import (
// ListStargazers list a repository's stargazers
func ListStargazers(ctx *context.APIContext) {
// swagger:operation GET /repos/{owner}/{repo}/stargazers repository repoListStargazers
// ---
// summary: List a repo's stargazers
// produces:
// - application/json
// parameters:
// - name: owner
// in: path
// description: owner of the repo
// type: string
// required: true
// - name: repo
// in: path
// description: name of the repo
// type: string
// required: true
// responses:
// "200":
// "$ref": "#/responses/UserList"
stargazers, err := ctx.Repo.Repository.GetStargazers(-1)
if err != nil {
ctx.Error(500, "GetStargazers", err)

122
routers/api/v1/repo/status.go
View file

@ -14,6 +14,34 @@ import (
// NewCommitStatus creates a new CommitStatus
func NewCommitStatus(ctx *context.APIContext, form api.CreateStatusOption) {
// swagger:operation POST /repos/{owner}/{repo}/statuses/{sha} repository repoCreateStatus
// ---
// summary: Create a commit status
// produces:
// - application/json
// parameters:
// - name: owner
// in: path
// description: owner of the repo
// type: string
// required: true
// - name: repo
// in: path
// description: name of the repo
// type: string
// required: true
// - name: sha
// in: path
// description: sha of the commit
// type: string
// required: true
// - name: body
// in: body
// schema:
// "$ref": "#/definitions/CreateStatusOption"
// responses:
// "200":
// "$ref": "#/responses/StatusList"
sha := ctx.Params("sha")
if len(sha) == 0 {
sha = ctx.Params("ref")
@ -43,10 +71,63 @@ func NewCommitStatus(ctx *context.APIContext, form api.CreateStatusOption) {
// GetCommitStatuses returns all statuses for any given commit hash
func GetCommitStatuses(ctx *context.APIContext) {
sha := ctx.Params("sha")
if len(sha) == 0 {
sha = ctx.Params("ref")
}
// swagger:operation GET /repos/{owner}/{repo}/statuses/{sha} repository repoListStatuses
// ---
// summary: Get a commit's statuses
// produces:
// - application/json
// parameters:
// - name: owner
// in: path
// description: owner of the repo
// type: string
// required: true
// - name: repo
// in: path
// description: name of the repo
// type: string
// required: true
// - name: sha
// in: path
// description: sha of the commit
// type: string
// required: true
// responses:
// "200":
// "$ref": "#/responses/StatusList"
getCommitStatuses(ctx, ctx.Params("sha"))
}
// GetCommitStatusesByRef returns all statuses for any given commit ref
func GetCommitStatusesByRef(ctx *context.APIContext) {
// swagger:operation GET /repos/{owner}/{repo}/commits/{ref}/statuses repository repoListStatusesByRef
// ---
// summary: Get a commit's statuses, by branch/tag/commit reference
// produces:
// - application/json
// parameters:
// - name: owner
// in: path
// description: owner of the repo
// type: string
// required: true
// - name: repo
// in: path
// description: name of the repo
// type: string
// required: true
// - name: ref
// in: path
// description: name of branch/tag/commit
// type: string
// required: true
// responses:
// "200":
// "$ref": "#/responses/StatusList"
getCommitStatuses(ctx, ctx.Params("ref"))
}
func getCommitStatuses(ctx *context.APIContext, sha string) {
if len(sha) == 0 {
ctx.Error(400, "ref/sha not given", nil)
return
@ -78,12 +159,33 @@ type combinedCommitStatus struct {
URL string `json:"url"`
}
// GetCombinedCommitStatus returns the combined status for any given commit hash
func GetCombinedCommitStatus(ctx *context.APIContext) {
sha := ctx.Params("sha")
if len(sha) == 0 {
sha = ctx.Params("ref")
}
// GetCombinedCommitStatusByRef returns the combined status for any given commit hash
func GetCombinedCommitStatusByRef(ctx *context.APIContext) {
// swagger:operation GET /repos/{owner}/{repo}/commits/{ref}/statuses repository repoGetCombinedStatusByRef
// ---
// summary: Get a commit's combined status, by branch/tag/commit reference
// produces:
// - application/json
// parameters:
// - name: owner
// in: path
// description: owner of the repo
// type: string
// required: true
// - name: repo
// in: path
// description: name of the repo
// type: string
// required: true
// - name: ref
// in: path
// description: name of branch/tag/commit
// type: string
// required: true
// responses:
// "200":
// "$ref": "#/responses/Status"
sha := ctx.Params("ref")
if len(sha) == 0 {
ctx.Error(400, "ref/sha not given", nil)
return

19
routers/api/v1/repo/subscriber.go
View file

@ -12,6 +12,25 @@ import (
// ListSubscribers list a repo's subscribers (i.e. watchers)
func ListSubscribers(ctx *context.APIContext) {
// swagger:operation GET /repos/{owner}/{repo}/subscribers repository repoListSubscribers
// ---
// summary: List a repo's watchers
// produces:
// - application/json
// parameters:
// - name: owner
// in: path
// description: owner of the repo
// type: string
// required: true
// - name: repo
// in: path
// description: name of the repo
// type: string
// required: true
// responses:
// "200":
// "$ref": "#/responses/UserList"
subscribers, err := ctx.Repo.Repository.GetWatchers(0)
if err != nil {
ctx.Error(500, "GetWatchers", err)