MieuxVoter
/
gitea-fork-majority-judgment
mirror of https://github.com/domi41/gitea.git
4
0
Fork 0
Code Issues 8 Releases Wiki Polls Activity

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
release/v1.3
Ethan Koenig 5 years ago committed by Lauris BH
parent 4287d100b3
commit f26f4a7e01
72 changed files with 9061 additions and 2509 deletions
Show Stats Download Patch File Download Diff File

2
Makefile
Unescape View File

@ -89,8 +89,6 @@ generate-swagger:
$(GO) get -u github.com/go-swagger/go-swagger/cmd/swagger; \
fi
swagger generate spec -o ./public/swagger.v1.json
$(SED_INPLACE) "s;\".ref\": \"#/definitions/GPGKey\";\"type\": \"object\";g" ./public/swagger.v1.json
$(SED_INPLACE) "s;^ \".ref\": \"#/definitions/Repository\"; \"type\": \"object\";g" ./public/swagger.v1.json
.PHONY: errcheck
errcheck:

13
modules/auth/repo_form.go
Unescape View File

@ -41,14 +41,17 @@ func (f *CreateRepoForm) Validate(ctx *macaron.Context, errs binding.Errors) bin
// MigrateRepoForm form for migrating repository
type MigrateRepoForm struct {
// required: true
CloneAddr string `json:"clone_addr" binding:"Required"`
AuthUsername string `json:"auth_username"`
AuthPassword string `json:"auth_password"`
UID int64 `json:"uid" binding:"Required"`
RepoName string `json:"repo_name" binding:"Required;AlphaDashDot;MaxSize(100)"`
Mirror bool `json:"mirror"`
Private bool `json:"private"`
Description string `json:"description" binding:"MaxSize(255)"`
// required: true
UID int64 `json:"uid" binding:"Required"`
// required: true
RepoName string `json:"repo_name" binding:"Required;AlphaDashDot;MaxSize(100)"`
Mirror bool `json:"mirror"`
Private bool `json:"private"`
Description string `json:"description" binding:"MaxSize(255)"`
}
// Validate validates the fields

7159
public/swagger.v1.json vendored
View File

File diff suppressed because it is too large Load Diff

34
routers/api/v1/admin/org.go
Unescape View File

@ -15,20 +15,26 @@ import (
// CreateOrg api for create organization
func CreateOrg(ctx *context.APIContext, form api.CreateOrgOption) {
// swagger:route POST /admin/users/{username}/orgs admin adminCreateOrg
//
// Consumes:
// - application/json
//
// Produces:
// - application/json
//
// Responses:
// 201: Organization
// 403: forbidden
// 422: validationError
// 500: error
// swagger:operation POST /admin/users/{username}/orgs admin adminCreateOrg
// ---
// summary: Create an organization
// consumes:
// - application/json
// produces:
// - application/json
// parameters:
// - name: username
// in: path
// description: username of the user that will own the created organization
// type: string
// required: true
// responses:
// "201":
// "$ref": "#/responses/Organization"
// "403":
// "$ref": "#/responses/forbidden"
// "422":
// "$ref": "#/responses/validationError"
u := user.GetUserByParams(ctx)
if ctx.Written() {
return

34
routers/api/v1/admin/repo.go
Unescape View File

@ -14,20 +14,26 @@ import (
// CreateRepo api for creating a repository
func CreateRepo(ctx *context.APIContext, form api.CreateRepoOption) {
// swagger:route POST /admin/users/{username}/repos admin adminCreateRepo
//
// Consumes:
// - application/json
//
// Produces:
// - application/json
//
// Responses:
// 201: Repository
// 403: forbidden
// 422: validationError
// 500: error
// swagger:operation POST /admin/users/{username}/repos admin adminCreateRepo
// ---
// summary: Create a repository on behalf a user
// consumes:
// - application/json
// produces:
// - application/json
// parameters:
// - name: username
// in: path
// description: username of the user. This user will own the created repository
// type: string
// required: true
// responses:
// "201":
// "$ref": "#/responses/Repository"
// "403":
// "$ref": "#/responses/forbidden"
// "422":
// "$ref": "#/responses/validationError"
owner := user.GetUserByParams(ctx)
if ctx.Written() {
return

139
routers/api/v1/admin/user.go
Unescape View File

@ -5,13 +5,12 @@
package admin
import (
api "code.gitea.io/sdk/gitea"
"code.gitea.io/gitea/models"
"code.gitea.io/gitea/modules/context"
"code.gitea.io/gitea/modules/log"
"code.gitea.io/gitea/modules/setting"
"code.gitea.io/gitea/routers/api/v1/user"
api "code.gitea.io/sdk/gitea"
)
func parseLoginSource(ctx *context.APIContext, u *models.User, sourceID int64, loginName string) {
@ -34,22 +33,27 @@ func parseLoginSource(ctx *context.APIContext, u *models.User, sourceID int64, l
u.LoginName = loginName
}
// CreateUser api for creating a user
// CreateUser create a user
func CreateUser(ctx *context.APIContext, form api.CreateUserOption) {
// swagger:route POST /admin/users admin adminCreateUser
//
// Consumes:
// - application/json
//
// Produces:
// - application/json
//
// Responses:
// 201: User
// 403: forbidden
// 422: validationError
// 500: error
// swagger:operation POST /admin/users admin adminCreateUser
// ---
// summary: Create a user
// consumes:
// - application/json
// produces:
// - application/json
// parameters:
// - name: body
// in: body
// schema:
// "$ref": "#/definitions/CreateUserOption"
// responses:
// "201":
// "$ref": "#/responses/User"
// "403":
// "$ref": "#/responses/forbidden"
// "422":
// "$ref": "#/responses/validationError"
u := &models.User{
Name: form.Username,
FullName: form.FullName,
@ -87,20 +91,30 @@ func CreateUser(ctx *context.APIContext, form api.CreateUserOption) {
// EditUser api for modifying a user's information
func EditUser(ctx *context.APIContext, form api.EditUserOption) {
// swagger:route PATCH /admin/users/{username} admin adminEditUser
//
// Consumes:
// - application/json
//
// Produces:
// - application/json
//
// Responses:
// 200: User
// 403: forbidden
// 422: validationError
// 500: error
// swagger:operation PATCH /admin/users/{username} admin adminEditUser
// ---
// summary: Edit an existing user
// consumes:
// - application/json
// produces:
// - application/json
// parameters:
// - name: username
// in: path
// description: username of user to edit
// type: string
// required: true
// - name: body
// in: body
// schema:
// "$ref": "#/definitions/EditUserOption"
// responses:
// "200":
// "$ref": "#/responses/User"
// "403":
// "$ref": "#/responses/forbidden"
// "422":
// "$ref": "#/responses/validationError"
u := user.GetUserByParams(ctx)
if ctx.Written() {
return
@ -157,17 +171,24 @@ func EditUser(ctx *context.APIContext, form api.EditUserOption) {
// DeleteUser api for deleting a user
func DeleteUser(ctx *context.APIContext) {
// swagger:route DELETE /admin/users/{username} admin adminDeleteUser
//
// Produces:
// - application/json
//
// Responses:
// 204: empty
// 403: forbidden
// 422: validationError
// 500: error
// swagger:operation DELETE /admin/users/{username} admin adminDeleteUser
// ---
// summary: Delete a user
// produces:
// - application/json
// parameters:
// - name: username
// in: path
// description: username of user to delete
// type: string
// required: true
// responses:
// "204":
// "$ref": "#/responses/empty"
// "403":
// "$ref": "#/responses/forbidden"
// "422":
// "$ref": "#/responses/validationError"
u := user.GetUserByParams(ctx)
if ctx.Written() {
return
@ -189,20 +210,26 @@ func DeleteUser(ctx *context.APIContext) {
// CreatePublicKey api for creating a public key to a user
func CreatePublicKey(ctx *context.APIContext, form api.CreateKeyOption) {
// swagger:route POST /admin/users/{username}/keys admin adminCreatePublicKey
//
// Consumes:
// - application/json
//
// Produces:
// - application/json
//
// Responses:
// 201: PublicKey
// 403: forbidden
// 422: validationError
// 500: error
// swagger:operation POST /admin/users/{username}/keys admin adminCreatePublicKey
// ---
// summary: Add a public key on behalf of a user
// consumes:
// - application/json
// produces:
// - application/json
// parameters:
// - name: username
// in: path
// description: username of the user
// type: string
// required: true
// responses:
// "201":
// "$ref": "#/responses/PublicKey"
// "403":
// "$ref": "#/responses/forbidden"
// "422":
// "$ref": "#/responses/validationError"
u := user.GetUserByParams(ctx)
if ctx.Written() {
return

23
routers/api/v1/api.go
Unescape View File

@ -4,11 +4,7 @@
// Package v1 Gitea API.
//
// This provide API interface to communicate with this Gitea instance.
//
// Terms Of Service:
//
// there are no TOS at this moment, use at your own risk we take no responsibility
// This documentation describes the Gitea API.
//
// Schemes: http, https
// BasePath: /api/v1
@ -51,11 +47,6 @@ package v1
import (
"strings"
"github.com/go-macaron/binding"
"gopkg.in/macaron.v1"
api "code.gitea.io/sdk/gitea"
"code.gitea.io/gitea/models"
"code.gitea.io/gitea/modules/auth"
"code.gitea.io/gitea/modules/context"
@ -63,8 +54,13 @@ import (
"code.gitea.io/gitea/routers/api/v1/misc"
"code.gitea.io/gitea/routers/api/v1/org"
"code.gitea.io/gitea/routers/api/v1/repo"
_ "code.gitea.io/gitea/routers/api/v1/swagger" // for swagger generation
"code.gitea.io/gitea/routers/api/v1/user"
"code.gitea.io/gitea/routers/api/v1/utils"
api "code.gitea.io/sdk/gitea"
"github.com/go-macaron/binding"
"gopkg.in/macaron.v1"
)
func repoAssignment() macaron.Handler {
@ -320,7 +316,7 @@ func RegisterRoutes(m *macaron.Macaron) {
m.Get("", user.GetAuthenticatedUser)
m.Combo("/emails").Get(user.ListEmails).
Post(bind(api.CreateEmailOption{}), user.AddEmail).
Delete(bind(api.CreateEmailOption{}), user.DeleteEmail)
Delete(bind(api.DeleteEmailOption{}), user.DeleteEmail)
m.Get("/followers", user.ListMyFollowers)
m.Group("/following", func() {
@ -435,7 +431,6 @@ func RegisterRoutes(m *macaron.Macaron) {
m.Combo("").Get(repo.ListTrackedTimes).
Post(reqToken(), bind(api.AddTimeOption{}), repo.AddTime)
})
})
}, mustEnableIssues)
m.Group("/labels", func() {
@ -484,8 +479,8 @@ func RegisterRoutes(m *macaron.Macaron) {
Post(reqToken(), reqRepoWriter(), bind(api.CreateStatusOption{}), repo.NewCommitStatus)
})
m.Group("/commits/:ref", func() {
m.Get("/status", repo.GetCombinedCommitStatus)
m.Get("/statuses", repo.GetCommitStatuses)
m.Get("/status", repo.GetCombinedCommitStatusByRef)
m.Get("/statuses", repo.GetCommitStatusesByRef)
})
}, repoAssignment())
})

50
routers/api/v1/misc/markdown.go
Unescape View File

@ -15,18 +15,23 @@ import (
// Markdown render markdown document to HTML
func Markdown(ctx *context.APIContext, form api.MarkdownOption) {
// swagger:route POST /markdown miscellaneous renderMarkdown
//
// Consumes:
// - application/json
//
// Produces:
// swagger:operation POST /markdown miscellaneous renderMarkdown
// ---
// summary: Render a markdown document as HTML
// parameters:
// - name: body
// in: body
// schema:
// "$ref": "#/definitions/MarkdownOption"
// consumes:
// - application/json
// produces:
// - text/html
//
// Responses:
// 200: MarkdownRender
// 422: validationError
// responses:
// "200":
// "$ref": "#/responses/MarkdownRender"
// "422":
// "$ref": "#/responses/validationError"
if ctx.HasAPIError() {
ctx.Error(422, "", ctx.GetErrMsg())
return
@ -53,17 +58,22 @@ func Markdown(ctx *context.APIContext, form api.MarkdownOption) {
// MarkdownRaw render raw markdown HTML
func MarkdownRaw(ctx *context.APIContext) {
// swagger:route POST /markdown/raw miscellaneous renderMarkdownRaw
//
// Consumes:
// swagger:operation POST /markdown/raw miscellaneous renderMarkdownRaw
// ---
// summary: Render raw markdown as HTML
// parameters:
// - name: body
// in: body
// type: string
// consumes:
// - text/plain
//
// Produces:
// produces:
// - text/html
//
// Responses:
// 200: MarkdownRender
// 422: validationError
// responses:
// "200":
// "$ref": "#/responses/MarkdownRender"
// "422":
// "$ref": "#/responses/validationError"
body, err := ctx.Req.Body().Bytes()
if err != nil {
ctx.Error(422, "", err)

20
routers/api/v1/misc/version.go
Unescape View File

@ -12,17 +12,13 @@ import (
// Version shows the version of the Gitea server
func Version(ctx *context.APIContext) {
// swagger:route GET /version miscellaneous getVersion
//
// Return Gitea running version.
//
// This show current running Gitea application version.
//
// Produces:
// - application/json
//
// Responses:
// 200: ServerVersion
// swagger:operation GET /version miscellaneous getVersion
// ---
// summary: Returns the version of the Gitea application
// produces:
// - application/json
// responses:
// "200":
// "$ref": "#/responses/ServerVersion"
ctx.JSON(200, &gitea.ServerVersion{Version: setting.AppVer})
}

100
routers/api/v1/org/hook.go
Unescape View File

@ -15,15 +15,14 @@ import (
// ListHooks list an organziation's webhooks
func ListHooks(ctx *context.APIContext) {
// swagger:route GET /orgs/{orgname}/hooks organization orgListHooks
//
// Produces:
// - application/json
//
// Responses:
// 200: HookList
// 500: error
// swagger:operation GET /orgs/{org}/hooks organization orgListHooks
// ---
// summary: List an organization's webhooks
// produces:
// - application/json
// responses:
// "200":
// "$ref": "#/responses/HookList"
org := ctx.Org.Organization
orgHooks, err := models.GetWebhooksByOrgID(org.ID)
if err != nil {
@ -39,16 +38,14 @@ func ListHooks(ctx *context.APIContext) {
// GetHook get an organization's hook by id
func GetHook(ctx *context.APIContext) {
// swagger:route GET /orgs/{orgname}/hooks/{id} organization orgGetHook
//
// Produces:
// - application/json
//
// Responses:
// 200: Hook
// 404: notFound
// 500: error
// swagger:operation GET /orgs/{org}/hooks/{id} organization orgGetHook
// ---
// summary: Get a hook
// produces:
// - application/json
// responses:
// "200":
// "$ref": "#/responses/Hook"
org := ctx.Org.Organization
hookID := ctx.ParamsInt64(":id")
hook, err := utils.GetOrgHook(ctx, org.ID, hookID)
@ -60,19 +57,16 @@ func GetHook(ctx *context.APIContext) {
// CreateHook create a hook for an organization
func CreateHook(ctx *context.APIContext, form api.CreateHookOption) {
// swagger:route POST /orgs/{orgname}/hooks/ organization orgCreateHook
//
// Consumes:
// - application/json
//
// Produces:
// - application/json
//
// Responses:
// 201: Hook
// 422: validationError
// 500: error
// swagger:operation POST /orgs/{org}/hooks/ organization orgCreateHook
// ---
// summary: Create a hook
// consumes:
// - application/json
// produces:
// - application/json
// responses:
// "201":
// "$ref": "#/responses/Hook"
if !utils.CheckCreateHookOption(ctx, &form) {
return
}
@ -81,36 +75,30 @@ 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 /orgs/{orgname}/hooks/{id} organization orgEditHook
//
// Consumes:
// - application/json
//
// Produces:
// - application/json
//
// Responses:
// 200: Hook
// 422: validationError
// 404: notFound
// 500: error
// swagger:operation PATCH /orgs/{org}/hooks/{id} organization orgEditHook
// ---
// summary: Update a hook
// consumes:
// - application/json
// produces:
// - application/json
// responses:
// "200":
// "$ref": "#/responses/Hook"
hookID := ctx.ParamsInt64(":id")
utils.EditOrgHook(ctx, &form, hookID)
}
// DeleteHook delete a hook of an organization
func DeleteHook(ctx *context.APIContext) {
// swagger:route DELETE /orgs/{orgname}/hooks/{id} organization orgDeleteHook
//
// Produces:
// - application/json
//
// Responses:
// 204: empty
// 404: notFound
// 500: error
// swagger:operation DELETE /orgs/{org}/hooks/{id} organization orgDeleteHook
// ---
// summary: Delete a hook
// produces:
// - application/json
// responses:
// "204":
// "$ref": "#/responses/empty"
org := ctx.Org.Organization
hookID := ctx.ParamsInt64(":id")
if err := models.DeleteWebhookByOrgID(org.ID, hookID); err != nil {

201
routers/api/v1/org/member.go
Unescape View File

@ -53,45 +53,68 @@ func listMembers(ctx *context.APIContext, publicOnly bool) {
// ListMembers list an organization's members
func ListMembers(ctx *context.APIContext) {
// swagger:route GET /orgs/{orgname}/members organization orgListMembers
//
// Produces:
// - application/json
//
// Responses:
// 200: UserList
// 500: error
// swagger:operation GET /orgs/{org}/members organization orgListMembers
// ---
// summary: List an organization's members
// produces:
// - application/json
// parameters:
// - name: org
// in: path
// description: name of the organization
// type: string
// required: true
// responses:
// "200":
// "$ref": "#/responses/UserList"
publicOnly := ctx.User == nil || !ctx.Org.Organization.IsOrgMember(ctx.User.ID)
listMembers(ctx, publicOnly)
}
// ListPublicMembers list an organization's public members
func ListPublicMembers(ctx *context.APIContext) {
// swagger:route GET /orgs/{orgname}/public_members organization orgListPublicMembers
//
// Produces:
// - application/json
//
// Responses:
// 200: UserList
// 500: error
// swagger:operation GET /orgs/{org}/public_members organization orgListPublicMembers
// ---
// summary: List an organization's public members
// parameters:
// - name: org
// in: path
// description: name of the organization
// type: string
// required: true
// produces:
// - application/json
// responses:
// "200":
// "$ref": "#/responses/UserList"
listMembers(ctx, true)
}
// IsMember check if a user is a member of an organization
func IsMember(ctx *context.APIContext) {
// swagger:route GET /orgs/{orgname}/members/{username} organization orgIsMember
//
// Produces:
// - application/json
//
// Responses:
// 204: empty
// 302: redirect
// 404: notFound
// swagger:operation GET /orgs/{org}/members/{username} organization orgIsMember
// ---
// summary: Check if a user is a member of an organization
// parameters:
// - name: org
// in: path
// description: name of the organization
// type: string
// required: true
// - name: username
// in: path
// description: username of the user
// type: string
// required: true
// responses:
// "204":
// description: user is a member
// schema:
// "$ref": "#/responses/empty"
// "404":
// description: user is not a member
// schema:
// "$ref": "#/responses/empty"
userToCheck := user.GetUserByParams(ctx)
if ctx.Written() {
return
@ -113,15 +136,29 @@ func IsMember(ctx *context.APIContext) {
// IsPublicMember check if a user is a public member of an organization
func IsPublicMember(ctx *context.APIContext) {
// swagger:route GET /orgs/{orgname}/public_members/{username} organization orgIsPublicMember
//
// Produces:
// - application/json
//
// Responses:
// 204: empty
// 404: notFound
// swagger:operation GET /orgs/{org}/public_members/{username} organization orgIsPublicMember
// ---
// summary: Check if a user is a public member of an organization
// parameters:
// - name: org
// in: path
// description: name of the organization
// type: string
// required: true
// - name: username
// in: path
// description: username of the user
// type: string
// required: true
// responses:
// "204":
// description: user is a public member
// schema:
// "$ref": "#/responses/empty"
// "404":
// description: user is not a public member
// schema:
// "$ref": "#/responses/empty"
userToCheck := user.GetUserByParams(ctx)
if ctx.Written() {
return
@ -135,16 +172,27 @@ func IsPublicMember(ctx *context.APIContext) {
// PublicizeMember make a member's membership public
func PublicizeMember(ctx *context.APIContext) {
// swagger:route PUT /orgs/{orgname}/public_members/{username} organization orgPublicizeMember
//
// Produces:
// - application/json
//
// Responses:
// 204: empty
// 403: forbidden
// 500: error
// swagger:operation PUT /orgs/{org}/public_members/{username} organization orgPublicizeMember
// ---
// summary: Publicize a user's membership
// produces:
// - application/json
// parameters:
// - name: org
// in: path
// description: name of the organization
// type: string
// required: true
// - name: username
// in: path
// description: username of the user
// type: string
// required: true
// responses:
// "204":
// description: membership publicized
// schema:
// "$ref": "#/responses/empty"
userToPublicize := user.GetUserByParams(ctx)
if ctx.Written() {
return
@ -163,16 +211,25 @@ func PublicizeMember(ctx *context.APIContext) {
// ConcealMember make a member's membership not public
func ConcealMember(ctx *context.APIContext) {
// swagger:route DELETE /orgs/{orgname}/public_members/{username} organization orgConcealMember
//
// Produces:
// - application/json
//
// Responses:
// 204: empty
// 403: forbidden
// 500: error
// swagger:operation DELETE /orgs/{org}/public_members/{username} organization orgConcealMember
// ---
// summary: Conceal a user's membership
// produces:
// - application/json
// parameters:
// - name: org
// in: path
// description: name of the organization
// type: string
// required: true
// - name: username
// in: path
// description: username of the user
// type: string
// required: true
// responses:
// "204":
// "$ref": "#/responses/empty"
userToConceal := user.GetUserByParams(ctx)
if ctx.Written() {
return
@ -191,15 +248,27 @@ func ConcealMember(ctx *context.APIContext) {
// DeleteMember remove a member from an organization
func DeleteMember(ctx *context.APIContext) {
// swagger:route DELETE /orgs/{orgname}/members/{username} organization orgDeleteMember
//
// Produces:
// - application/json
//
// Responses:
// 204: empty
// 500: error
// swagger:operation DELETE /orgs/{org}/members/{username} organization orgDeleteMember
// ---
// summary: Remove a member from an organization
// produces:
// - application/json
// parameters:
// - name: org
// in: path
// description: name of the organization
// type: string
// required: true
// - name: username
// in: path
// description: username of the user
// type: string
// required: true
// responses:
// "204":
// description: member removed
// schema:
// "$ref": "#/responses/empty"
member := user.GetUserByParams(ctx)
if ctx.Written() {
return

59
routers/api/v1/org/org.go
Unescape View File

@ -27,14 +27,33 @@ func listUserOrgs(ctx *context.APIContext, u *models.User, all bool) {
}
// ListMyOrgs list all my orgs
// see https://github.com/gogits/go-gogs-client/wiki/Organizations#list-your-organizations
func ListMyOrgs(ctx *context.APIContext) {
// swagger:operation GET /user/orgs organization orgListCurrentUserOrgs
// ---
// summary: List the current user's organizations
// produces:
// - application/json
// responses:
// "200":
// "$ref": "#/responses/OrganizationList"
listUserOrgs(ctx, ctx.User, true)
}
// ListUserOrgs list user's orgs
// see https://github.com/gogits/go-gogs-client/wiki/Organizations#list-user-organizations
func ListUserOrgs(ctx *context.APIContext) {
// swagger:operation GET /user/{username}/orgs organization orgListUserOrgs
// ---
// summary: List a user's organizations
// produces:
// - application/json
// parameters:
// - name: username
// in: path
// description: username of user
// type: string
// responses:
// "200":
// "$ref": "#/responses/OrganizationList"
u := user.GetUserByParams(ctx)
if ctx.Written() {
return
@ -43,14 +62,46 @@ func ListUserOrgs(ctx *context.APIContext) {
}
// Get get an organization
// see https://github.com/gogits/go-gogs-client/wiki/Organizations#get-an-organization
func Get(ctx *context.APIContext) {
// swagger:operation GET /orgs/{org} organization orgGet
// ---
// summary: Get an organization
// produces:
// - application/json
// parameters:
// - name: org
// in: path
// description: name of the organization to get
// type: string
// required: true
// responses:
// "200":
// "$ref": "#/responses/Organization"
ctx.JSON(200, convert.ToOrganization(ctx.Org.Organization))
}
// Edit change an organization's information
// see https://github.com/gogits/go-gogs-client/wiki/Organizations#edit-an-organization
func Edit(ctx *context.APIContext, form api.EditOrgOption) {
// swagger:operation PATCH /orgs/{org} organization orgEdit
// ---
// summary: Edit an organization
// consumes:
// - application/json
// produces:
// - application/json
// parameters:
// - name: org
// in: path
// description: name of the organization to edit
// type: string
// required: true
// - name: body
// in: body
// schema:
// "$ref": "#/definitions/EditOrgOption"
// responses:
// "200":
// "$ref": "#/responses/Organization"
org := ctx.Org.Organization
org.FullName = form.FullName
org.Description = form.Description

198
routers/api/v1/org/team.go
Unescape View File

@ -15,6 +15,20 @@ import (
// ListTeams list all the teams of an organization
func ListTeams(ctx *context.APIContext) {
// swagger:operation GET /orgs/{org}/teams organization orgListTeams
// ---
// summary: List an organization's teams
// produces:
// - application/json
// parameters:
// - name: org
// in: path
// description: name of the organization
// type: string
// required: true
// responses:
// "200":
// "$ref": "#/responses/TeamList"
org := ctx.Org.Organization
if err := org.GetTeams(); err != nil {
ctx.Error(500, "GetTeams", err)
@ -30,11 +44,45 @@ func ListTeams(ctx *context.APIContext) {
// GetTeam api for get a team
func GetTeam(ctx *context.APIContext) {
// swagger:operation GET /teams/{id} organization orgGetTeam
// ---
// summary: Get a team
// produces:
// - application/json
// parameters:
// - name: id
// in: path
// description: id of the team to get
// type: integer
// required: true
// responses:
// "200":
// "$ref": "#/responses/Team"
ctx.JSON(200, convert.ToTeam(ctx.Org.Team))
}
// CreateTeam api for create a team
func CreateTeam(ctx *context.APIContext, form api.CreateTeamOption) {
// swagger:operation POST /orgs/{org}/teams organization orgCreateTeam
// ---
// summary: Create a team
// consumes:
// - application/json
// produces:
// - application/json
// parameters:
// - name: org
// in: path
// description: name of the organization
// type: string
// required: true
// - name: body
// in: body
// schema:
// "$ref": "#/definitions/CreateTeamOption"
// responses:
// "201":
// "$ref": "#/responses/Team"
team := &models.Team{
OrgID: ctx.Org.Organization.ID,
Name: form.Name,
@ -55,6 +103,26 @@ func CreateTeam(ctx *context.APIContext, form api.CreateTeamOption) {
// EditTeam api for edit a team
func EditTeam(ctx *context.APIContext, form api.EditTeamOption) {
// swagger:operation PATCH /teams/{id} organization orgEditTeam
// ---
// summary: Edit a team
// consumes:
// - application/json
// produces:
// - application/json
// parameters:
// - name: id
// in: path
// description: id of the team to edit
// type: integer
// required: true
// - name: body
// in: body
// schema:
// "$ref": "#/definitions/EditTeamOption"
// responses:
// "200":
// "$ref": "#/responses/Team"
team := &models.Team{
ID: ctx.Org.Team.ID,
OrgID: ctx.Org.Team.OrgID,
@ -71,6 +139,20 @@ func EditTeam(ctx *context.APIContext, form api.EditTeamOption) {
// DeleteTeam api for delete a team
func DeleteTeam(ctx *context.APIContext) {
// swagger:operation DELETE /teams/{id} organization orgDeleteTeam
// ---
// summary: Delete a team
// parameters:
// - name: id
// in: path
// description: id of the team to delete
// type: integer
// required: true
// responses:
// "204":
// description: team deleted
// schema:
// "$ref": "#/responses/empty"
if err := models.DeleteTeam(ctx.Org.Team); err != nil {
ctx.Error(500, "DeleteTeam", err)
return
@ -80,6 +162,20 @@ func DeleteTeam(ctx *context.APIContext) {
// GetTeamMembers api for get a team's members
func GetTeamMembers(ctx *context.APIContext) {
// swagger:operation GET /teams/{id}/members organization orgListTeamMembers
// ---
// summary: List a team's members
// produces:
// - application/json
// parameters:
// - name: id
// in: path
// description: id of the team
// type: integer
// required: true
// responses:
// "200":
// "$ref": "#/responses/UserList"
if !models.IsOrganizationMember(ctx.Org.Team.OrgID, ctx.User.ID) {
ctx.Status(404)
return
@ -98,6 +194,25 @@ func GetTeamMembers(ctx *context.APIContext) {
// AddTeamMember api for add a member to a team
func AddTeamMember(ctx *context.APIContext) {
// swagger:operation PUT /teams/{id}/members/{username} organization orgAddTeamMember
// ---
// summary: Add a team member
// produces:
// - application/json
// parameters:
// - name: id
// in: path
// description: id of the team
// type: integer
// required: true
// - name: username
// in: path
// description: username of the user to add
// type: string
// required: true
// responses:
// "204":
// "$ref": "#/responses/empty"
u := user.GetUserByParams(ctx)
if ctx.Written() {
return
@ -111,6 +226,25 @@ func AddTeamMember(ctx *context.APIContext) {
// RemoveTeamMember api for remove one member from a team
func RemoveTeamMember(ctx *context.APIContext) {
// swagger:operation DELETE /teams/{id}/members/{username} organization orgAddTeamMember
// ---
// summary: Remove a team member
// produces:
// - application/json
// parameters:
// - name: id
// in: path
// description: id of the team
// type: integer
// required: true
// - name: username
// in: path
// description: username of the user to remove
// type: string
// required: true
// responses:
// "204":
// "$ref": "#/responses/empty"
u := user.GetUserByParams(ctx)
if ctx.Written() {
return
@ -125,6 +259,20 @@ func RemoveTeamMember(ctx *context.APIContext) {
// GetTeamRepos api for get a team's repos
func GetTeamRepos(ctx *context.APIContext) {
// swagger:operation GET /teams/{id}/repos organization orgListTeamRepos
// ---
// summary: List a team's repos
// produces:
// - application/json
// parameters:
// - name: id
// in: path
// description: id of the team
// type: integer
// required: true
// responses:
// "200":
// "$ref": "#/responses/RepositoryList"
team := ctx.Org.Team
if err := team.GetRepositories(); err != nil {
ctx.Error(500, "GetTeamRepos", err)
@ -157,6 +305,30 @@ func getRepositoryByParams(ctx *context.APIContext) *models.Repository {
// AddTeamRepository api for adding a repository to a team
func AddTeamRepository(ctx *context.APIContext) {
// swagger:operation PUT /teams/{id}/repos/{org}/{repo} organization orgAddTeamMember
// ---
// summary: Add a repository to a team
// produces:
// - application/json
// parameters:
// - name: id
// in: path
// description: id of the team
// type: integer
// required: true
// - name: org
// in: path
// description: organization that owns the repo to add
// type: string
// required: true
// - name: repo
// in: path
// description: name of the repo to add
// type: string
// required: true
// responses:
// "204":
// "$ref": "#/responses/empty"
repo := getRepositoryByParams(ctx)
if ctx.Written() {
return
@ -177,6 +349,32 @@ func AddTeamRepository(ctx *context.APIContext) {
// RemoveTeamRepository api for removing a repository from a team
func RemoveTeamRepository(ctx *context.APIContext) {
// swagger:operation DELETE /teams/{id}/repos/{org}/{repo} organization orgAddTeamMember
// ---
// summary: Remove a repository from a team
// description: This does not delete the repository, it only removes the
// repository from the team.
// produces:
// - application/json
// parameters:
// - name: id
// in: path
// description: id of the team
// type: integer
// required: true
// - name: org
// in: path
// description: organization that owns the repo to remove
// type: string
// required: true
// - name: repo
// in: path
// description: name of the repo to remove
// type: string
// required: true
// responses:
// "204":
// "$ref": "#/responses/empty"
repo := getRepositoryByParams(ctx)
if ctx.Written() {
return

45
routers/api/v1/repo/branch.go
Unescape 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
Unescape 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
Unescape 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
Unescape 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: