tdsds.com/gitea
1
1
Fork 0
mirror of https://github.com/go-gitea/gitea synced 2025-07-22 18:28:37 +00:00
Code Releases 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
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

39
routers/api/v1/user/app.go
View File

@@ -13,15 +13,14 @@ import (
// ListAccessTokens list all the access tokens
func ListAccessTokens(ctx *context.APIContext) {
// swagger:route GET /users/{username}/tokens user userGetTokens
//
// Produces:
// - application/json
//
// Responses:
// 200: AccessTokenList
// 500: error
// swagger:operation GET /users/{username}/tokens user userGetTokens
// ---
// summary: List the authenticated user's access tokens
// produces:
// - application/json
// responses:
// "200":
// "$ref": "#/responses/AccessTokenList"
tokens, err := models.ListAccessTokens(ctx.User.ID)
if err != nil {
ctx.Error(500, "ListAccessTokens", err)
@@ -40,18 +39,16 @@ func ListAccessTokens(ctx *context.APIContext) {
// CreateAccessToken create access tokens
func CreateAccessToken(ctx *context.APIContext, form api.CreateAccessTokenOption) {
// swagger:route POST /users/{username} /tokens user userCreateToken
//
// Consumes:
// - application/json
//
// Produces:
// - application/json
//
// Responses:
// 200: AccessToken
// 500: error
// swagger:operation POST /users/{username}/tokens user userCreateToken
// ---
// summary: Create an access token
// consumes:
// - application/json
// produces:
// - application/json
// responses:
// "200":
// "$ref": "#/responses/AccessToken"
t := &models.AccessToken{
UID: ctx.User.ID,
Name: form.Name,

47
routers/api/v1/user/email.go
View File

@@ -13,9 +13,17 @@ import (
"code.gitea.io/gitea/routers/api/v1/convert"
)
// ListEmails list all the emails of mine
// ListEmails list all of the authenticated user's email addresses
// see https://github.com/gogits/go-gogs-client/wiki/Users-Emails#list-email-addresses-for-a-user
func ListEmails(ctx *context.APIContext) {
// swagger:operation GET /user/emails user userListEmails
// ---
// summary: List the authenticated user's email addresses
// produces:
// - application/json
// responses:
// "200":
// "$ref": "#/responses/EmailList"
emails, err := models.GetEmailAddresses(ctx.User.ID)
if err != nil {
ctx.Error(500, "GetEmailAddresses", err)
@@ -28,9 +36,26 @@ func ListEmails(ctx *context.APIContext) {
ctx.JSON(200, &apiEmails)
}
// AddEmail add email for me
// see https://github.com/gogits/go-gogs-client/wiki/Users-Emails#add-email-addresses
// AddEmail add an email address
func AddEmail(ctx *context.APIContext, form api.CreateEmailOption) {
// swagger:operation POST /user/emails user userAddEmail
// ---
// summary: Add email addresses
// produces:
// - application/json
// parameters:
// - name: options
// in: body
// schema:
// "$ref": "#/definitions/CreateEmailOption"
// parameters:
// - name: body
// in: body
// schema:
// "$ref": "#/definitions/CreateEmailOption"
// responses:
// '201':
// "$ref": "#/responses/EmailList"
if len(form.Emails) == 0 {
ctx.Status(422)
return
@@ -62,8 +87,20 @@ func AddEmail(ctx *context.APIContext, form api.CreateEmailOption) {
}
// DeleteEmail delete email
// see https://github.com/gogits/go-gogs-client/wiki/Users-Emails#delete-email-addresses
func DeleteEmail(ctx *context.APIContext, form api.CreateEmailOption) {
func DeleteEmail(ctx *context.APIContext, form api.DeleteEmailOption) {
// swagger:operation DELETE /user/emails user userDeleteEmail
// ---
// summary: Delete email addresses
// produces:
// - application/json
// parameters:
// - name: body
// in: body
// schema:
// "$ref": "#/definitions/DeleteEmailOption"
// responses:
// "204":
// "$ref": "#/responses/empty"
if len(form.Emails) == 0 {
ctx.Status(204)
return

177
routers/api/v1/user/follower.go
View File

@@ -28,31 +28,35 @@ func listUserFollowers(ctx *context.APIContext, u *models.User) {
responseAPIUsers(ctx, users)
}
// ListMyFollowers list all my followers
// ListMyFollowers list the authenticated user's followers
func ListMyFollowers(ctx *context.APIContext) {
// swagger:route GET /user/followers user userCurrentListFollowers
//
// Produces:
// - application/json
//
// Responses:
// 200: UserList
// 500: error
// swagger:operation GET /user/followers user userCurrentListFollowers
// ---
// summary: List the authenticated user's followers
// produces:
// - application/json
// responses:
// "200":
// "$ref": "#/responses/UserList"
listUserFollowers(ctx, ctx.User)
}
// ListFollowers list user's followers
// ListFollowers list the given user's followers
func ListFollowers(ctx *context.APIContext) {
// swagger:route GET /users/:username/followers user userListFollowers
//
// Produces:
// - application/json
//
// Responses:
// 200: UserList
// 500: error
// swagger:operation GET /users/{username}/followers user userListFollowers
// ---
// summary: List the given user's followers
// produces:
// - application/json
// parameters:
// - name: username
// in: path
// description: username of user
// type: string
// required: true
// responses:
// "200":
// "$ref": "#/responses/UserList"
u := GetUserByParams(ctx)
if ctx.Written() {
return
@@ -69,31 +73,35 @@ func listUserFollowing(ctx *context.APIContext, u *models.User) {
responseAPIUsers(ctx, users)
}
// ListMyFollowing list all my followings
// ListMyFollowing list the users that the authenticated user is following
func ListMyFollowing(ctx *context.APIContext) {
// swagger:route GET /user/following user userCurrentListFollowing
//
// Produces:
// - application/json
//
// Responses:
// 200: UserList
// 500: error
// swagger:operation GET /user/following user userCurrentListFollowing
// ---
// summary: List the users that the authenticated user is following
// produces:
// - application/json
// responses:
// "200":
// "$ref": "#/responses/UserList"
listUserFollowing(ctx, ctx.User)
}
// ListFollowing list user's followings
// ListFollowing list the users that the given user is following
func ListFollowing(ctx *context.APIContext) {
// swagger:route GET /users/{username}/following user userListFollowing
//
// Produces:
// - application/json
//
// Responses:
// 200: UserList
// 500: error
// swagger:operation GET /users/{username}/following user userListFollowing
// ---
// summary: List the users that the given user is following
// produces:
// - application/json
// parameters:
// - name: username
// in: path
// description: username of user
// type: string
// required: true
// responses:
// "200":
// "$ref": "#/responses/UserList"
u := GetUserByParams(ctx)
if ctx.Written() {
return
@@ -109,14 +117,22 @@ func checkUserFollowing(ctx *context.APIContext, u *models.User, followID int64)
}
}
// CheckMyFollowing check if the repo is followed by me
// CheckMyFollowing whether the given user is followed by the authenticated user
func CheckMyFollowing(ctx *context.APIContext) {
// swagger:route GET /user/following/{username} user userCurrentCheckFollowing
//
// Responses:
// 204: empty
// 404: notFound
// swagger:operation GET /user/following/{followee} user userCurrentCheckFollowing
// ---
// summary: Check whether a user is followed by the authenticated user
// parameters:
// - name: followee
// in: path
// description: username of followed user
// type: string
// required: true
// responses:
// "204":
// "$ref": "#/responses/empty"
// "404":
// "$ref": "#/responses/notFound"
target := GetUserByParams(ctx)
if ctx.Written() {
return
@@ -124,14 +140,27 @@ func CheckMyFollowing(ctx *context.APIContext) {
checkUserFollowing(ctx, ctx.User, target.ID)
}
// CheckFollowing check if the repo is followed by user
// CheckFollowing check if one user is following another user
func CheckFollowing(ctx *context.APIContext) {
// swagger:route GET /users/{username}/following/:target user userCheckFollowing
//
// Responses:
// 204: empty
// 404: notFound
// swagger:operation GET /users/{follower}/following/{followee} user userCheckFollowing
// ---
// summary: Check if one user is following another user
// parameters:
// - name: follower
// in: path
// description: username of following user
// type: string
// required: true
// - name: followee
// in: path
// description: username of followed user
// type: string
// required: true
// responses:
// "204":
// "$ref": "#/responses/empty"
// "404":
// "$ref": "#/responses/notFound"
u := GetUserByParams(ctx)
if ctx.Written() {
return
@@ -143,14 +172,20 @@ func CheckFollowing(ctx *context.APIContext) {
checkUserFollowing(ctx, u, target.ID)
}
// Follow follow one repository
// Follow follow a user
func Follow(ctx *context.APIContext) {
// swagger:route PUT /user/following/{username} user userCurrentPutFollow
//
// Responses:
// 204: empty
// 500: error
// swagger:operation PUT /user/following/{username} user userCurrentPutFollow
// ---
// summary: Follow a user
// parameters:
// - name: username
// in: path
// description: username of user to follow
// type: string
// required: true
// responses:
// "204":
// "$ref": "#/responses/empty"
target := GetUserByParams(ctx)
if ctx.Written() {
return
@@ -162,14 +197,20 @@ func Follow(ctx *context.APIContext) {
ctx.Status(204)
}
// Unfollow unfollow one repository
// Unfollow unfollow a user
func Unfollow(ctx *context.APIContext) {
// swagger:route DELETE /user/following/{username} user userCurrentDeleteFollow
//
// Responses:
// 204: empty
// 500: error
// swagger:operation DELETE /user/following/{username} user userCurrentDeleteFollow
// ---
// summary: Unfollow a user
// parameters:
// - name: username
// in: path
// description: username of user to unfollow
// type: string
// required: true
// responses:
// "204":
// "$ref": "#/responses/empty"
target := GetUserByParams(ctx)
if ctx.Written() {
return

133
routers/api/v1/user/gpg_key.go
View File

@@ -34,15 +34,20 @@ func listGPGKeys(ctx *context.APIContext, uid int64) {
//ListGPGKeys get the GPG key list of a user
func ListGPGKeys(ctx *context.APIContext) {
// swagger:route GET /users/{username}/gpg_keys user userListGPGKeys
//
// Produces:
// - application/json
//
// Responses:
// 200: GPGKeyList
// 500: error
// swagger:operation GET /users/{username}/gpg_keys user userListGPGKeys
// ---
// summary: List the given user's GPG keys
// produces:
// - application/json
// parameters:
// - name: username
// in: path
// description: username of user
// type: string
// required: true
// responses:
// "200":
// "$ref": "#/responses/GPGKeyList"
user := GetUserByParams(ctx)
if ctx.Written() {
return
@@ -50,32 +55,37 @@ func ListGPGKeys(ctx *context.APIContext) {
listGPGKeys(ctx, user.ID)
}
//ListMyGPGKeys get the GPG key list of the logged user
//ListMyGPGKeys get the GPG key list of the authenticated user
func ListMyGPGKeys(ctx *context.APIContext) {
// swagger:route GET /user/gpg_keys user userCurrentListGPGKeys
//
// Produces:
// - application/json
//
// Responses:
// 200: GPGKeyList
// 500: error
// swagger:operation GET /user/gpg_keys user userCurrentListGPGKeys
// ---
// summary: List the authenticated user's GPG keys
// produces:
// - application/json
// responses:
// "200":
// "$ref": "#/responses/GPGKeyList"
listGPGKeys(ctx, ctx.User.ID)
}
//GetGPGKey get the GPG key based on a id
func GetGPGKey(ctx *context.APIContext) {
// swagger:route GET /user/gpg_keys/{id} user userCurrentGetGPGKey
//
// Produces:
// - application/json
//
// Responses:
// 200: GPGKey
// 404: notFound
// 500: error
// swagger:operation GET /user/gpg_keys/{id} user userCurrentGetGPGKey
// ---
// summary: Get a GPG key
// produces:
// - application/json
// parameters:
// - name: id
// in: path
// description: id of key to get
// type: integer
// required: true
// responses:
// "200":
// "$ref": "#/responses/GPGKey"
// "404":
// "$ref": "#/responses/notFound"
key, err := models.GetGPGKeyByID(ctx.ParamsInt64(":id"))
if err != nil {
if models.IsErrGPGKeyNotExist(err) {
@@ -98,36 +108,47 @@ func CreateUserGPGKey(ctx *context.APIContext, form api.CreateGPGKeyOption, uid
ctx.JSON(201, convert.ToGPGKey(key))
}
//CreateGPGKey associate a GPG key to the current user
func CreateGPGKey(ctx *context.APIContext, form api.CreateGPGKeyOption) {
// swagger:route POST /user/gpg_keys user userCurrentPostGPGKey
//
// Consumes:
// - application/json
//
// Produces:
// - application/json
//
// Responses:
// 201: GPGKey
// 422: validationError
// 500: error
// swagger:parameters userCurrentPostGPGKey
type swaggerUserCurrentPostGPGKey struct {
// in:body
Form api.CreateGPGKeyOption
}
//CreateGPGKey create a GPG key belonging to the authenticated user
func CreateGPGKey(ctx *context.APIContext, form api.CreateGPGKeyOption) {
// swagger:operation POST /user/gpg_keys user userCurrentPostGPGKey
// ---
// summary: Create a GPG key
// consumes:
// - application/json
// produces:
// - application/json
// responses:
// "201":
// "$ref": "#/responses/GPGKey"
// "422":
// "$ref": "#/responses/validationError"
CreateUserGPGKey(ctx, form, ctx.User.ID)
}
//DeleteGPGKey remove a GPG key associated to the current user
//DeleteGPGKey remove a GPG key belonging to the authenticated user
func DeleteGPGKey(ctx *context.APIContext) {
// swagger:route DELETE /user/gpg_keys/{id} user userCurrentDeleteGPGKey
//
// Produces:
// - application/json
//
// Responses:
// 204: empty
// 403: forbidden
// 500: error
// swagger:operation DELETE /user/gpg_keys/{id} user userCurrentDeleteGPGKey
// ---
// summary: Remove a GPG key
// produces:
// - application/json
// parameters:
// - name: id
// in: path
// description: id of key to delete
// type: integer
// required: true
// responses:
// "204":
// "$ref": "#/responses/empty"
// "403":
// "$ref": "#/responses/forbidden"
if err := models.DeleteGPGKey(ctx.User, ctx.ParamsInt64(":id")); err != nil {
if models.IsErrGPGKeyAccessDenied(err) {
ctx.Error(403, "", "You do not have access to this key")
@@ -144,9 +165,9 @@ func DeleteGPGKey(ctx *context.APIContext) {
func HandleAddGPGKeyError(ctx *context.APIContext, err error) {
switch {
case models.IsErrGPGKeyAccessDenied(err):
ctx.Error(422, "", "You do not have access to this gpg key")
ctx.Error(422, "", "You do not have access to this GPG key")
case models.IsErrGPGKeyIDAlreadyUsed(err):
ctx.Error(422, "", "A key with the same keyid is already in database")
ctx.Error(422, "", "A key with the same id already exists")
default:
ctx.Error(500, "AddGPGKey", err)
}

130
routers/api/v1/user/key.go
View File

@@ -53,31 +53,35 @@ func listPublicKeys(ctx *context.APIContext, uid int64) {
ctx.JSON(200, &apiKeys)
}
// ListMyPublicKeys list all my public keys
// ListMyPublicKeys list all of the authenticated user's public keys
func ListMyPublicKeys(ctx *context.APIContext) {
// swagger:route GET /user/keys user userCurrentListKeys
//
// Produces:
// - application/json
//
// Responses:
// 200: PublicKeyList
// 500: error
// swagger:operation GET /user/keys user userCurrentListKeys
// ---
// summary: List the authenticated user's public keys
// produces:
// - application/json
// responses:
// "200":
// "$ref": "#/responses/PublicKeyList"
listPublicKeys(ctx, ctx.User.ID)
}
// ListPublicKeys list all user's public keys
// ListPublicKeys list the given user's public keys
func ListPublicKeys(ctx *context.APIContext) {
// swagger:route GET /users/{username}/keys user userListKeys
//
// Produces:
// - application/json
//
// Responses:
// 200: PublicKeyList
// 500: error
// swagger:operation GET /users/{username}/keys user userListKeys
// ---
// summary: List the given user's public keys
// produces:
// - application/json
// parameters:
// - name: username
// in: path
// description: username of user
// type: string
// required: true
// responses:
// "200":
// "$ref": "#/responses/PublicKeyList"
user := GetUserByParams(ctx)
if ctx.Written() {
return
@@ -85,18 +89,24 @@ func ListPublicKeys(ctx *context.APIContext) {
listPublicKeys(ctx, user.ID)
}
// GetPublicKey get one public key
// GetPublicKey get a public key
func GetPublicKey(ctx *context.APIContext) {
// swagger:route GET /user/keys/{id} user userCurrentGetKey
//
// Produces:
// - application/json
//
// Responses:
// 200: PublicKey
// 404: notFound
// 500: error
// swagger:operation GET /user/keys/{id} user userCurrentGetKey
// ---
// summary: Get a public key
// produces:
// - application/json
// parameters:
// - name: id
// in: path
// description: id of key to get
// type: integer
// required: true
// responses:
// "200":
// "$ref": "#/responses/PublicKey"
// "404":
// "$ref": "#/responses/notFound"
key, err := models.GetPublicKeyByID(ctx.ParamsInt64(":id"))
if err != nil {
if models.IsErrKeyNotExist(err) {
@@ -130,34 +140,44 @@ func CreateUserPublicKey(ctx *context.APIContext, form api.CreateKeyOption, uid
// CreatePublicKey create one public key for me
func CreatePublicKey(ctx *context.APIContext, form api.CreateKeyOption) {
// swagger:route POST /user/keys user userCurrentPostKey
//
// Consumes:
// - application/json
//
// Produces:
// - application/json
//
// Responses:
// 201: PublicKey
// 422: validationError
// 500: error
// swagger:operation POST /user/keys user userCurrentPostKey
// ---
// summary: Create a public key
// consumes:
// - application/json
// produces:
// - application/json
// parameters:
// - name: body
// in: body
// schema:
// "$ref": "#/definitions/CreateKeyOption"
// responses:
// "201":
// "$ref": "#/responses/PublicKey"
// "422":
// "$ref": "#/responses/validationError"
CreateUserPublicKey(ctx, form, ctx.User.ID)
}
// DeletePublicKey delete one public key of mine
// DeletePublicKey delete one public key
func DeletePublicKey(ctx *context.APIContext) {
// swagger:route DELETE /user/keys/{id} user userCurrentDeleteKey
//
// Produces:
// - application/json
//
// Responses:
// 204: empty
// 403: forbidden
// 500: error
// swagger:operation DELETE /user/keys/{id} user userCurrentDeleteKey
// ---
// summary: Delete a public key
// produces:
// - application/json
// parameters:
// - name: id
// in: path
// description: id of key to delete
// type: integer
// required: true
// responses:
// "204":
// "$ref": "#/responses/empty"
// "403":
// "$ref": "#/responses/forbidden"
if err := models.DeletePublicKey(ctx.User, ctx.ParamsInt64(":id")); err != nil {
if models.IsErrKeyAccessDenied(err) {
ctx.Error(403, "", "You do not have access to this key")

62
routers/api/v1/user/repo.go
View File

@@ -36,15 +36,20 @@ func listUserRepos(ctx *context.APIContext, u *models.User) {
// ListUserRepos - list the repos owned by the given user.
func ListUserRepos(ctx *context.APIContext) {
// swagger:route GET /users/{username}/repos user userListRepos
//
// Produces:
// - application/json
//
// Responses:
// 200: RepositoryList
// 500: error
// swagger:operation GET /users/{username}/repos user userListRepos
// ---
// summary: List the repos owned by the given user
// produces:
// - application/json
// parameters:
// - name: username
// in: path
// description: username of user
// type: string
// required: true
// responses:
// "200":
// "$ref": "#/responses/RepositoryList"
user := GetUserByParams(ctx)
if ctx.Written() {
return
@@ -54,14 +59,14 @@ func ListUserRepos(ctx *context.APIContext) {
// ListMyRepos - list the repositories you own or have access to.
func ListMyRepos(ctx *context.APIContext) {
// swagger:route GET /user/repos user userCurrentListRepos
//
// Produces:
// - application/json
//
// Responses:
// 200: RepositoryList
// 500: error
// swagger:operation GET /user/repos user userCurrentListRepos
// ---
// summary: List the repos that the authenticated user owns or has access to
// produces:
// - application/json
// responses:
// "200":
// "$ref": "#/responses/RepositoryList"
ownRepos, err := models.GetUserRepositories(ctx.User.ID, true, 1, ctx.User.NumRepos, "")
if err != nil {
ctx.Error(500, "GetUserRepositories", err)
@@ -87,14 +92,19 @@ func ListMyRepos(ctx *context.APIContext) {
// ListOrgRepos - list the repositories of an organization.
func ListOrgRepos(ctx *context.APIContext) {
// swagger:route GET /orgs/{orgname}/repos organization orgListRepos
//
// Produces:
// - application/json
//
// Responses:
// 200: RepositoryList
// 500: error
// swagger:operation GET /orgs/{org}/repos organization orgListRepos
// ---
// summary: List an organization's repos
// produces:
// - application/json
// parameters:
// - name: org
// in: path
// description: name of the organization
// type: string
// required: true
// responses:
// "200":
// "$ref": "#/responses/RepositoryList"
listUserRepos(ctx, ctx.Org.Organization)
}

114
routers/api/v1/user/star.go
View File

@@ -30,18 +30,22 @@ func getStarredRepos(userID int64, private bool) ([]*api.Repository, error) {
return repos, nil
}
// GetStarredRepos returns the repos that the user specified by the APIContext
// has starred
// GetStarredRepos returns the repos that the given user has starred
func GetStarredRepos(ctx *context.APIContext) {
// swagger:route GET /users/{username}/starred user userListStarred
//
// Produces:
// - application/json
//
// Responses:
// 200: RepositoryList
// 500: error
// swagger:operation GET /users/{username}/starred user userListStarred
// ---
// summary: The repos that the given user has starred
// produces:
// - application/json
// parameters:
// - name: username
// in: path
// description: username of user
// type: string
// required: true
// responses:
// "200":
// "$ref": "#/responses/RepositoryList"
user := GetUserByParams(ctx)
private := user.ID == ctx.User.ID
repos, err := getStarredRepos(user.ID, private)
@@ -53,15 +57,14 @@ func GetStarredRepos(ctx *context.APIContext) {
// GetMyStarredRepos returns the repos that the authenticated user has starred
func GetMyStarredRepos(ctx *context.APIContext) {
// swagger:route GET /user/starred user userCurrentListStarred
//
// Produces:
// - application/json
//
// Responses:
// 200: RepositoryList
// 500: error
// swagger:operation GET /user/starred user userCurrentListStarred
// ---
// summary: The repos that the authenticated user has starred
// produces:
// - application/json
// responses:
// "200":
// "$ref": "#/responses/RepositoryList"
repos, err := getStarredRepos(ctx.User.ID, true)
if err != nil {
ctx.Error(500, "getStarredRepos", err)
@@ -71,12 +74,25 @@ func GetMyStarredRepos(ctx *context.APIContext) {
// IsStarring returns whether the authenticated is starring the repo
func IsStarring(ctx *context.APIContext) {
// swagger:route GET /user/starred/{username}/{reponame} user userCurrentCheckStarring
//
// Responses:
// 204: empty
// 404: notFound
// swagger:operation GET /user/starred/{owner}/{repo} user userCurrentCheckStarring
// ---
// summary: Whether the authenticated is starring the repo
// 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:
// "204":
// "$ref": "#/responses/empty"
// "404":
// "$ref": "#/responses/notFound"
if models.IsStaring(ctx.User.ID, ctx.Repo.Repository.ID) {
ctx.Status(204)
} else {
@@ -86,12 +102,23 @@ func IsStarring(ctx *context.APIContext) {
// Star the repo specified in the APIContext, as the authenticated user
func Star(ctx *context.APIContext) {
// swagger:route PUT /user/starred/{username}/{reponame} user userCurrentPutStar
//
// Responses:
// 204: empty
// 500: error
// swagger:operation PUT /user/starred/{owner}/{repo} user userCurrentPutStar
// ---
// summary: Star the given repo
// parameters:
// - name: owner
// in: path
// description: owner of the repo to star
// type: string
// required: true
// - name: repo
// in: path
// description: name of the repo to star
// type: string
// required: true
// responses:
// "204":
// "$ref": "#/responses/empty"
err := models.StarRepo(ctx.User.ID, ctx.Repo.Repository.ID, true)
if err != nil {
ctx.Error(500, "StarRepo", err)
@@ -102,12 +129,23 @@ func Star(ctx *context.APIContext) {
// Unstar the repo specified in the APIContext, as the authenticated user
func Unstar(ctx *context.APIContext) {
// swagger:route DELETE /user/starred/{username}/{reponame} user userCurrentDeleteStar
//
// Responses:
// 204: empty
// 500: error
// swagger:operation DELETE /user/starred/{owner}/{repo} user userCurrentDeleteStar
// ---
// summary: Unstar the given repo
// parameters:
// - name: owner
// in: path
// description: owner of the repo to unstar
// type: string
// required: true
// - name: repo
// in: path
// description: name of the repo to unstar
// type: string
// required: true
// responses:
// "204":
// "$ref": "#/responses/empty"
err := models.StarRepo(ctx.User.ID, ctx.Repo.Repository.ID, false)
if err != nil {
ctx.Error(500, "StarRepo", err)

70
routers/api/v1/user/user.go
View File

@@ -17,15 +17,23 @@ import (
// Search search users
func Search(ctx *context.APIContext) {
// swagger:route GET /users/search user userSearch
//
// Produces:
// - application/json
//
// Responses:
// 200: UserList
// 500: error
// swagger:operation GET /users/search user userSearch
// ---
// summary: Search for users
// produces:
// - application/json
// parameters:
// - name: q
// in: query
// description: keyword
// type: string
// - name: limit
// in: query
// description: maximum number of users to return
// type: integer
// responses:
// "200":
// "$ref": "#/responses/UserList"
opts := &models.SearchUserOptions{
Keyword: strings.Trim(ctx.Query("q"), " "),
Type: models.UserTypeIndividual,
@@ -65,16 +73,22 @@ func Search(ctx *context.APIContext) {
// GetInfo get user's information
func GetInfo(ctx *context.APIContext) {
// swagger:route GET /users/{username} user userGet
//
// Produces:
// - application/json
//
// Responses:
// 200: User
// 404: notFound
// 500: error
// swagger:operation GET /users/{username} user userGet
// ---
// summary: Get a user
// produces:
// - application/json
// parameters:
// - name: username
// in: path
// description: username of user to get
// type: string
// required: true
// responses:
// "200":
// "$ref": "#/responses/User"
// "404":
// "$ref": "#/responses/notFound"
u, err := models.GetUserByName(ctx.Params(":username"))
if err != nil {
if models.IsErrUserNotExist(err) {
@@ -92,15 +106,15 @@ func GetInfo(ctx *context.APIContext) {
ctx.JSON(200, u.APIFormat())
}
// GetAuthenticatedUser get curent user's information
// GetAuthenticatedUser get current user's information
func GetAuthenticatedUser(ctx *context.APIContext) {
// swagger:route GET /user user userGetCurrent
//
// Produces:
// - application/json
//
// Responses:
// 200: User
// swagger:operation GET /user user userGetCurrent
// ---
// summary: Get the authenticated user
// produces:
// - application/json
// responses:
// "200":
// "$ref": "#/responses/User"
ctx.JSON(200, ctx.User.APIFormat())
}

108
routers/api/v1/user/watch.go
View File

@@ -33,15 +33,19 @@ func getWatchedRepos(userID int64, private bool) ([]*api.Repository, error) {
// GetWatchedRepos returns the repos that the user specified in ctx is watching
func GetWatchedRepos(ctx *context.APIContext) {
// swagger:route GET /users/{username}/subscriptions user userListSubscriptions
//
// Produces:
// - application/json
//
// Responses:
// 200: RepositoryList
// 500: error
// swagger:operation GET /users/{username}/subscriptions user userListSubscriptions
// ---
// summary: List the repositories watched by a user
// produces:
// - application/json
// parameters:
// - name: username
// type: string
// in: path
// description: username of the user
// responses:
// "200":
// "$ref": "#/responses/RepositoryList"
user := GetUserByParams(ctx)
private := user.ID == ctx.User.ID
repos, err := getWatchedRepos(user.ID, private)
@@ -53,15 +57,14 @@ func GetWatchedRepos(ctx *context.APIContext) {
// GetMyWatchedRepos returns the repos that the authenticated user is watching
func GetMyWatchedRepos(ctx *context.APIContext) {
// swagger:route GET /user/subscriptions user userCurrentListSubscriptions
//
// Produces:
// - application/json
//
// Responses:
// 200: RepositoryList
// 500: error
// swagger:operation GET /user/subscriptions user userCurrentListSubscriptions
// ---
// summary: List repositories watched by the authenticated user
// produces:
// - application/json
// responses:
// "200":
// "$ref": "#/responses/RepositoryList"
repos, err := getWatchedRepos(ctx.User.ID, true)
if err != nil {
ctx.Error(500, "getWatchedRepos", err)
@@ -72,12 +75,23 @@ func GetMyWatchedRepos(ctx *context.APIContext) {
// IsWatching returns whether the authenticated user is watching the repo
// specified in ctx
func IsWatching(ctx *context.APIContext) {
// swagger:route GET /repos/{username}/{reponame}/subscription repository userCurrentCheckSubscription
//
// Responses:
// 200: WatchInfo
// 404: notFound
// swagger:operation GET /repos/{owner}/{repo}/subscription repository userCurrentCheckSubscription
// ---
// summary: Check if the current user is watching a repo
// 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/WatchInfo"
if models.IsWatching(ctx.User.ID, ctx.Repo.Repository.ID) {
ctx.JSON(200, api.WatchInfo{
Subscribed: true,
@@ -94,12 +108,23 @@ func IsWatching(ctx *context.APIContext) {
// Watch the repo specified in ctx, as the authenticated user
func Watch(ctx *context.APIContext) {
// swagger:route PUT /repos/{username}/{reponame}/subscription repository userCurrentPutSubscription
//
// Responses:
// 200: WatchInfo
// 500: error
// swagger:operation PUT /repos/{owner}/{repo}/subscription repository userCurrentPutSubscription
// ---
// summary: Watch a repo
// 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/WatchInfo"
err := models.WatchRepo(ctx.User.ID, ctx.Repo.Repository.ID, true)
if err != nil {
ctx.Error(500, "WatchRepo", err)
@@ -118,12 +143,23 @@ func Watch(ctx *context.APIContext) {
// Unwatch the repo specified in ctx, as the authenticated user
func Unwatch(ctx *context.APIContext) {
// swagger:route DELETE /repos/{username}/{reponame}/subscription repository userCurrentDeleteSubscription
//
// Responses:
// 204: empty
// 500: error
// swagger:operation DELETE /repos/{owner}/{repo}/subscription repository userCurrentDeleteSubscription
// ---
// summary: Unwatch a repo
// 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:
// "204":
// "$ref": "#/responses/empty"
err := models.WatchRepo(ctx.User.ID, ctx.Repo.Repository.ID, false)
if err != nil {
ctx.Error(500, "UnwatchRepo", err)