Update swagger documentation (#2899)

* Update swagger documentation

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

* Restore delete comments

9 files changed, 547 insertions, 333 deletions

diff --git a/routers/api/v1/user/app.go b/routers/api/v1/user/app.go
index 1d722e36e4..e1f75de683 100644
--- a/routers/api/v1/user/app.go
+++ b/routers/api/v1/user/app.go
@@ -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,
diff --git a/routers/api/v1/user/email.go b/routers/api/v1/user/email.go
index 0d83aa38c1..1d071e697f 100644
--- a/routers/api/v1/user/email.go
+++ b/routers/api/v1/user/email.go
@@ -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
diff --git a/routers/api/v1/user/follower.go b/routers/api/v1/user/follower.go
index 55a0b032db..49d13cc380 100644
--- a/routers/api/v1/user/follower.go
+++ b/routers/api/v1/user/follower.go
@@ -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
diff --git a/routers/api/v1/user/gpg_key.go b/routers/api/v1/user/gpg_key.go
index 96ff6e88ba..a955f3ff14 100644
--- a/routers/api/v1/user/gpg_key.go
+++ b/routers/api/v1/user/gpg_key.go
@@ -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)
 	}
diff --git a/routers/api/v1/user/key.go b/routers/api/v1/user/key.go
index 1772ef4d25..3649dac9b9 100644
--- a/routers/api/v1/user/key.go
+++ b/routers/api/v1/user/key.go
@@ -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")
diff --git a/routers/api/v1/user/repo.go b/routers/api/v1/user/repo.go
index f119632e39..38fe76cad4 100644
--- a/routers/api/v1/user/repo.go
+++ b/routers/api/v1/user/repo.go
@@ -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)
 }
diff --git a/routers/api/v1/user/star.go b/routers/api/v1/user/star.go
index 6f943a2712..1cf4f5239c 100644
--- a/routers/api/v1/user/star.go
+++ b/routers/api/v1/user/star.go
@@ -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)
diff --git a/routers/api/v1/user/user.go b/routers/api/v1/user/user.go
index 799cec0804..0453a455f4 100644
--- a/routers/api/v1/user/user.go
+++ b/routers/api/v1/user/user.go
@@ -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())
 }
diff --git a/routers/api/v1/user/watch.go b/routers/api/v1/user/watch.go
index 18628c91d1..b10831f5f2 100644
--- a/routers/api/v1/user/watch.go
+++ b/routers/api/v1/user/watch.go
@@ -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)