Generate swagger json (#1402)

- Generate swagger.json into public/
- Add swagger-ui auto-installation
- Add footer link to local swagger-ui
- Add /swagger url for using app url.
- Fix Swagger-UI version via git tag

13 files changed, 481 insertions, 38 deletions

diff --git a/routers/api/v1/api.go b/routers/api/v1/api.go
index e33dc12d28..96e3830a21 100644
--- a/routers/api/v1/api.go
+++ b/routers/api/v1/api.go
@@ -2,6 +2,31 @@
 // Use of this source code is governed by a MIT-style
 // license that can be found in the LICENSE file.
 
+//go:generate swagger generate spec -o ../../../public/swagger.v1.json
+//go:generate sed -i "s;\".ref\": \"#/definitions/GPGKey\";\"type\": \"object\";g" ../../../public/swagger.v1.json
+
+// 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
+//
+//     Schemes: http, https
+//     BasePath: /api/v1
+//     Version: 1.1.1
+//     License: MIT http://opensource.org/licenses/MIT
+//
+//     Consumes:
+//     - application/json
+//     - text/plain
+//
+//     Produces:
+//     - application/json
+//     - text/html
+//
+// swagger:meta
 package v1
 
 import (
diff --git a/routers/api/v1/misc/markdown.go b/routers/api/v1/misc/markdown.go
index 188594e83e..0d346a9270 100644
--- a/routers/api/v1/misc/markdown.go
+++ b/routers/api/v1/misc/markdown.go
@@ -13,8 +13,19 @@ import (
 )
 
 // Markdown render markdown document to HTML
-// see https://github.com/gogits/go-gogs-client/wiki/Miscellaneous#render-an-arbitrary-markdown-document
 func Markdown(ctx *context.APIContext, form api.MarkdownOption) {
+	// swagger:route POST /markdown renderMarkdown
+	//
+	//     Consumes:
+	//     - application/json
+	//
+	//     Produces:
+	//     - text/html
+	//
+	//     Responses:
+	//       200: MarkdownRender
+	//       422: validationError
+
 	if ctx.HasAPIError() {
 		ctx.Error(422, "", ctx.GetErrMsg())
 		return
@@ -40,8 +51,18 @@ func Markdown(ctx *context.APIContext, form api.MarkdownOption) {
 }
 
 // MarkdownRaw render raw markdown HTML
-// see https://github.com/gogits/go-gogs-client/wiki/Miscellaneous#render-a-markdown-document-in-raw-mode
 func MarkdownRaw(ctx *context.APIContext) {
+	// swagger:route POST /markdown/raw renderMarkdownRaw
+	//
+	//     Consumes:
+	//     - text/plain
+	//
+	//     Produces:
+	//     - text/html
+	//
+	//     Responses:
+	//       200: MarkdownRender
+	//       422: validationError
 	body, err := ctx.Req.Body().Bytes()
 	if err != nil {
 		ctx.Error(422, "", err)
diff --git a/routers/api/v1/misc/version.go b/routers/api/v1/misc/version.go
index 92950c19c3..ed4107eb33 100644
--- a/routers/api/v1/misc/version.go
+++ b/routers/api/v1/misc/version.go
@@ -12,5 +12,17 @@ import (
 
 // Version shows the version of the Gitea server
 func Version(ctx *context.APIContext) {
+	// swagger:route GET /version getVersion
+	//
+	// Return Gitea running version.
+	//
+	// This show current running Gitea application version.
+	//
+	//     Produces:
+	//     - application/json
+	//
+	//     Responses:
+	//       200: ServerVersion
+	
 	ctx.JSON(200, &gitea.ServerVersion{Version: setting.AppVer})
 }
diff --git a/routers/api/v1/repo/hook.go b/routers/api/v1/repo/hook.go
index 2e3b655a12..93dcd081d7 100644
--- a/routers/api/v1/repo/hook.go
+++ b/routers/api/v1/repo/hook.go
@@ -14,8 +14,16 @@ import (
 )
 
 // ListHooks list all hooks of a repository
-// see https://github.com/gogits/go-gogs-client/wiki/Repositories#list-hooks
 func ListHooks(ctx *context.APIContext) {
+	// swagger:route GET /repos/{username}/{reponame}/hooks
+	//
+	//     Produces:
+	//     - application/json
+	//
+	//     Responses:
+	//       200: apiHooks
+	//       500: error
+
 	hooks, err := models.GetWebhooksByRepoID(ctx.Repo.Repository.ID)
 	if err != nil {
 		ctx.Error(500, "GetWebhooksByRepoID", err)
@@ -41,8 +49,20 @@ func GetHook(ctx *context.APIContext) {
 }
 
 // CreateHook create a hook for a repository
-// see https://github.com/gogits/go-gogs-client/wiki/Repositories#create-a-hook
 func CreateHook(ctx *context.APIContext, form api.CreateHookOption) {
+	// swagger:route POST /repos/{username}/{reponame}/hooks
+	//
+	//     Consumes:
+	//     - application/json
+	//
+	//     Produces:
+	//     - application/json
+	//
+	//     Responses:
+	//       200: apiHook
+	//       422: validationError
+	//       500: error
+
 	if !utils.CheckCreateHookOption(ctx, &form) {
 		return
 	}
@@ -50,14 +70,33 @@ func CreateHook(ctx *context.APIContext, form api.CreateHookOption) {
 }
 
 // EditHook modify a hook of a repository
-// see https://github.com/gogits/go-gogs-client/wiki/Repositories#edit-a-hook
 func EditHook(ctx *context.APIContext, form api.EditHookOption) {
+	// swagger:route PATCH /repos/{username}/{reponame}/hooks/{id}
+	//
+	//     Produces:
+	//     - application/json
+	//
+	//     Responses:
+	//       200: apiHook //TODO
+	//       422: validationError
+	//       500: error
+
 	hookID := ctx.ParamsInt64(":id")
 	utils.EditRepoHook(ctx, &form, hookID)
 }
 
 // DeleteHook delete a hook of a repository
 func DeleteHook(ctx *context.APIContext) {
+	// swagger:route DELETE /repos/{username}/{reponame}/hooks/{id}
+	//
+	//     Produces:
+	//     - application/json
+	//
+	//     Responses:
+	//       204: empty
+	//       404: notFound
+	//       500: error
+
 	if err := models.DeleteWebhookByRepoID(ctx.Repo.Repository.ID, ctx.ParamsInt64(":id")); err != nil {
 		if models.IsErrWebhookNotExist(err) {
 			ctx.Status(404)
diff --git a/routers/api/v1/repo/repo.go b/routers/api/v1/repo/repo.go
index c0b8bb3d7b..83b1dbd26b 100644
--- a/routers/api/v1/repo/repo.go
+++ b/routers/api/v1/repo/repo.go
@@ -18,8 +18,16 @@ import (
 )
 
 // Search repositories via options
-// see https://github.com/gogits/go-gogs-client/wiki/Repositories#search-repositories
 func Search(ctx *context.APIContext) {
+	// swagger:route GET /repos/search repoSearch
+	//
+	//     Produces:
+	//     - application/json
+	//
+	//     Responses:
+	//       200: SearchResults
+	//       500: SearchError
+
 	opts := &models.SearchRepoOptions{
 		Keyword:  strings.Trim(ctx.Query("q"), " "),
 		OwnerID:  ctx.QueryInt64("uid"),
@@ -33,9 +41,9 @@ func Search(ctx *context.APIContext) {
 		} else {
 			u, err := models.GetUserByID(opts.OwnerID)
 			if err != nil {
-				ctx.JSON(500, map[string]interface{}{
-					"ok":    false,
-					"error": err.Error(),
+				ctx.JSON(500, api.SearchError{
+					OK:    false,
+					Error: err.Error(),
 				})
 				return
 			}
@@ -48,9 +56,9 @@ func Search(ctx *context.APIContext) {
 
 	repos, count, err := models.SearchRepositoryByName(opts)
 	if err != nil {
-		ctx.JSON(500, map[string]interface{}{
-			"ok":    false,
-			"error": err.Error(),
+		ctx.JSON(500, api.SearchError{
+			OK:    false,
+			Error: err.Error(),
 		})
 		return
 	}
@@ -63,26 +71,26 @@ func Search(ctx *context.APIContext) {
 	results := make([]*api.Repository, len(repos))
 	for i, repo := range repos {
 		if err = repo.GetOwner(); err != nil {
-			ctx.JSON(500, map[string]interface{}{
-				"ok":    false,
-				"error": err.Error(),
+			ctx.JSON(500, api.SearchError{
+				OK:    false,
+				Error: err.Error(),
 			})
 			return
 		}
 		accessMode, err := models.AccessLevel(userID, repo)
 		if err != nil {
-			ctx.JSON(500, map[string]interface{}{
-				"ok":    false,
-				"error": err.Error(),
+			ctx.JSON(500, api.SearchError{
+				OK:    false,
+				Error: err.Error(),
 			})
 		}
 		results[i] = repo.APIFormat(accessMode)
 	}
 
 	ctx.SetLinkHeader(int(count), setting.API.MaxResponseItems)
-	ctx.JSON(200, map[string]interface{}{
-		"ok":   true,
-		"data": results,
+	ctx.JSON(200, api.SearchResults{
+		OK:   true,
+		Data: results,
 	})
 }
 
@@ -129,6 +137,20 @@ func Create(ctx *context.APIContext, opt api.CreateRepoOption) {
 
 // CreateOrgRepo create one repository of the organization
 func CreateOrgRepo(ctx *context.APIContext, opt api.CreateRepoOption) {
+	// swagger:route POST /org/{org}/repos createOrgRepo
+	//
+	//     Consumes:
+	//     - application/json
+	//
+	//     Produces:
+	//     - application/json
+	//
+	//     Responses:
+	//       201: Repository
+	//       422: validationError
+	//       403: forbidden
+	//       500: error
+
 	org, err := models.GetOrgByName(ctx.Params(":org"))
 	if err != nil {
 		if models.IsErrUserNotExist(err) {
@@ -147,8 +169,20 @@ func CreateOrgRepo(ctx *context.APIContext, opt api.CreateRepoOption) {
 }
 
 // Migrate migrate remote git repository to gitea
-// see https://github.com/gogits/go-gogs-client/wiki/Repositories#migrate
 func Migrate(ctx *context.APIContext, form auth.MigrateRepoForm) {
+	// swagger:route POST /repos/migrate
+	//
+	//     Consumes:
+	//     - application/json
+	//
+	//     Produces:
+	//     - application/json
+	//
+	//     Responses:
+	//       201: Repository
+	//       422: validationError
+	//       500: error
+
 	ctxUser := ctx.User
 	// Not equal means context user is an organization,
 	// or is another user/organization if current user is admin.
@@ -220,8 +254,16 @@ func Migrate(ctx *context.APIContext, form auth.MigrateRepoForm) {
 }
 
 // Get one repository
-// see https://github.com/gogits/go-gogs-client/wiki/Repositories#get
 func Get(ctx *context.APIContext) {
+	// swagger:route GET /repos/{username}/{reponame}
+	//
+	//     Produces:
+	//     - application/json
+	//
+	//     Responses:
+	//       200: Repository
+	//       500: error
+
 	repo := ctx.Repo.Repository
 	access, err := models.AccessLevel(ctx.User.ID, repo)
 	if err != nil {
@@ -233,6 +275,15 @@ func Get(ctx *context.APIContext) {
 
 // GetByID returns a single Repository
 func GetByID(ctx *context.APIContext) {
+	// swagger:route GET /repositories/{id}
+	//
+	//     Produces:
+	//     - application/json
+	//
+	//     Responses:
+	//       200: Repository
+	//       500: error
+
 	repo, err := models.GetRepositoryByID(ctx.ParamsInt64(":id"))
 	if err != nil {
 		if models.IsErrRepoNotExist(err) {
@@ -252,8 +303,17 @@ func GetByID(ctx *context.APIContext) {
 }
 
 // Delete one repository
-// see https://github.com/gogits/go-gogs-client/wiki/Repositories#delete
 func Delete(ctx *context.APIContext) {
+	// swagger:route DELETE /repos/{username}/{reponame}
+	//
+	//     Produces:
+	//     - application/json
+	//
+	//     Responses:
+	//       204: empty
+	//       403: forbidden
+	//       500: error
+
 	if !ctx.Repo.IsAdmin() {
 		ctx.Error(403, "", "Must have admin rights")
 		return
diff --git a/routers/api/v1/user/app.go b/routers/api/v1/user/app.go
index 6d5a271f79..88837a71a2 100644
--- a/routers/api/v1/user/app.go
+++ b/routers/api/v1/user/app.go
@@ -12,8 +12,16 @@ import (
 )
 
 // ListAccessTokens list all the access tokens
-// see https://github.com/gogits/go-gogs-client/wiki/Users#list-access-tokens-for-a-user
 func ListAccessTokens(ctx *context.APIContext) {
+	// swagger:route GET /users/{username}/tokens userGetTokens
+	//
+	//     Produces:
+	//     - application/json
+	//
+	//     Responses:
+	//       200: AccessTokenList
+	//       500: error
+
 	tokens, err := models.ListAccessTokens(ctx.User.ID)
 	if err != nil {
 		ctx.Error(500, "ListAccessTokens", err)
@@ -31,8 +39,19 @@ func ListAccessTokens(ctx *context.APIContext) {
 }
 
 // CreateAccessToken create access tokens
-// see https://github.com/gogits/go-gogs-client/wiki/Users#create-a-access-token
 func CreateAccessToken(ctx *context.APIContext, form api.CreateAccessTokenOption) {
+	// swagger:route POST /users/{username} /tokens userCreateToken
+	//
+	//     Consumes:
+	//     - application/json
+	//
+	//     Produces:
+	//     - application/json
+	//
+	//     Responses:
+	//       200: AccessToken
+	//       500: error
+
 	t := &models.AccessToken{
 		UID:  ctx.User.ID,
 		Name: form.Name,
diff --git a/routers/api/v1/user/follower.go b/routers/api/v1/user/follower.go
index ff043c9de9..84240c7957 100644
--- a/routers/api/v1/user/follower.go
+++ b/routers/api/v1/user/follower.go
@@ -30,12 +30,29 @@ func listUserFollowers(ctx *context.APIContext, u *models.User) {
 
 // ListMyFollowers list all my followers
 func ListMyFollowers(ctx *context.APIContext) {
+	// swagger:route GET /user/followers userCurrentListFollowers
+	//
+	//     Produces:
+	//     - application/json
+	//
+	//     Responses:
+	//       200: UserList
+	//       500: error
+
 	listUserFollowers(ctx, ctx.User)
 }
 
 // ListFollowers list user's followers
-// see https://github.com/gogits/go-gogs-client/wiki/Users-Followers#list-followers-of-a-user
 func ListFollowers(ctx *context.APIContext) {
+	// swagger:route GET /users/:username/followers userListFollowers
+	//
+	//     Produces:
+	//     - application/json
+	//
+	//     Responses:
+	//       200: UserList
+	//       500: error
+
 	u := GetUserByParams(ctx)
 	if ctx.Written() {
 		return
@@ -54,12 +71,29 @@ func listUserFollowing(ctx *context.APIContext, u *models.User) {
 
 // ListMyFollowing list all my followings
 func ListMyFollowing(ctx *context.APIContext) {
+	// swagger:route GET /user/following userCurrentListFollowing
+	//
+	//     Produces:
+	//     - application/json
+	//
+	//     Responses:
+	//       200: UserList
+	//       500: error
+
 	listUserFollowing(ctx, ctx.User)
 }
 
 // ListFollowing list user's followings
-// see https://github.com/gogits/go-gogs-client/wiki/Users-Followers#list-users-followed-by-another-user
 func ListFollowing(ctx *context.APIContext) {
+	// swagger:route GET /users/{username}/following userListFollowing
+	//
+	//     Produces:
+	//     - application/json
+	//
+	//     Responses:
+	//       200: UserList
+	//       500: error
+
 	u := GetUserByParams(ctx)
 	if ctx.Written() {
 		return
@@ -76,8 +110,13 @@ func checkUserFollowing(ctx *context.APIContext, u *models.User, followID int64)
 }
 
 // CheckMyFollowing check if the repo is followed by me
-// see https://github.com/gogits/go-gogs-client/wiki/Users-Followers#check-if-you-are-following-a-user
 func CheckMyFollowing(ctx *context.APIContext) {
+	// swagger:route GET /user/following/{username} userCurrentCheckFollowing
+	//
+	//     Responses:
+	//       204: empty
+	//       404: notFound
+
 	target := GetUserByParams(ctx)
 	if ctx.Written() {
 		return
@@ -86,8 +125,13 @@ func CheckMyFollowing(ctx *context.APIContext) {
 }
 
 // CheckFollowing check if the repo is followed by user
-// see https://github.com/gogits/go-gogs-client/wiki/Users-Followers#check-if-one-user-follows-another
 func CheckFollowing(ctx *context.APIContext) {
+	// swagger:route GET /users/{username}/following/:target userCheckFollowing
+	//
+	//     Responses:
+	//       204: empty
+	//       404: notFound
+
 	u := GetUserByParams(ctx)
 	if ctx.Written() {
 		return
@@ -100,8 +144,13 @@ func CheckFollowing(ctx *context.APIContext) {
 }
 
 // Follow follow one repository
-// see https://github.com/gogits/go-gogs-client/wiki/Users-Followers#follow-a-user
 func Follow(ctx *context.APIContext) {
+	// swagger:route PUT /user/following/{username} userCurrentPutFollow
+	//
+	//     Responses:
+	//       204: empty
+	//       500: error
+
 	target := GetUserByParams(ctx)
 	if ctx.Written() {
 		return
@@ -114,8 +163,13 @@ func Follow(ctx *context.APIContext) {
 }
 
 // Unfollow unfollow one repository
-// see https://github.com/gogits/go-gogs-client/wiki/Users-Followers#unfollow-a-user
 func Unfollow(ctx *context.APIContext) {
+	// swagger:route DELETE /user/following/{username} userCurrentDeleteFollow
+	//
+	//     Responses:
+	//       204: empty
+	//       500: error
+
 	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 bb4ae42431..678816ccda 100644
--- a/routers/api/v1/user/gpg_key.go
+++ b/routers/api/v1/user/gpg_key.go
@@ -34,6 +34,15 @@ 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 userListGPGKeys
+	//
+	//     Produces:
+	//     - application/json
+	//
+	//     Responses:
+	//       200: GPGKeyList
+	//       500: error
+
 	user := GetUserByParams(ctx)
 	if ctx.Written() {
 		return
@@ -43,11 +52,30 @@ func ListGPGKeys(ctx *context.APIContext) {
 
 //ListMyGPGKeys get the GPG key list of the logged user
 func ListMyGPGKeys(ctx *context.APIContext) {
+	// swagger:route GET /user/gpg_keys userCurrentListGPGKeys
+	//
+	//     Produces:
+	//     - application/json
+	//
+	//     Responses:
+	//       200: GPGKeyList
+	//       500: error
+
 	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} userCurrentGetGPGKey
+	//
+	//     Produces:
+	//     - application/json
+	//
+	//     Responses:
+	//       200: GPGKey
+	//       404: notFound
+	//       500: error
+
 	key, err := models.GetGPGKeyByID(ctx.ParamsInt64(":id"))
 	if err != nil {
 		if models.IsErrGPGKeyNotExist(err) {
@@ -72,11 +100,34 @@ func CreateUserGPGKey(ctx *context.APIContext, form api.CreateGPGKeyOption, uid
 
 //CreateGPGKey associate a GPG key to the current user
 func CreateGPGKey(ctx *context.APIContext, form api.CreateGPGKeyOption) {
+	// swagger:route POST /user/gpg_keys userCurrentPostGPGKey
+	//
+	//     Consumes:
+	//     - application/json
+	//
+	//     Produces:
+	//     - application/json
+	//
+	//     Responses:
+	//       201: GPGKey
+	//       422: validationError
+	//       500: error
+
 	CreateUserGPGKey(ctx, form, ctx.User.ID)
 }
 
 //DeleteGPGKey remove a GPG key associated to the current user
 func DeleteGPGKey(ctx *context.APIContext) {
+	// swagger:route DELETE /user/gpg_keys/{id} userCurrentDeleteGPGKey
+	//
+	//     Produces:
+	//     - application/json
+	//
+	//     Responses:
+	//       204: empty
+	//       403: forbidden
+	//       500: error
+
 	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")
diff --git a/routers/api/v1/user/key.go b/routers/api/v1/user/key.go
index 39a045df32..a53ed2f8c9 100644
--- a/routers/api/v1/user/key.go
+++ b/routers/api/v1/user/key.go
@@ -54,14 +54,30 @@ func listPublicKeys(ctx *context.APIContext, uid int64) {
 }
 
 // ListMyPublicKeys list all my public keys
-// see https://github.com/gogits/go-gogs-client/wiki/Users-Public-Keys#list-your-public-keys
 func ListMyPublicKeys(ctx *context.APIContext) {
+	// swagger:route GET /user/keys userCurrentListKeys
+	//
+	//     Produces:
+	//     - application/json
+	//
+	//     Responses:
+	//       200: PublicKeyList
+	//       500: error
+
 	listPublicKeys(ctx, ctx.User.ID)
 }
 
 // ListPublicKeys list all user's public keys
-// see https://github.com/gogits/go-gogs-client/wiki/Users-Public-Keys#list-public-keys-for-a-user
 func ListPublicKeys(ctx *context.APIContext) {
+	// swagger:route GET /users/{username}/keys userListKeys
+	//
+	//     Produces:
+	//     - application/json
+	//
+	//     Responses:
+	//       200: PublicKeyList
+	//       500: error
+
 	user := GetUserByParams(ctx)
 	if ctx.Written() {
 		return
@@ -70,8 +86,17 @@ func ListPublicKeys(ctx *context.APIContext) {
 }
 
 // GetPublicKey get one public key
-// see https://github.com/gogits/go-gogs-client/wiki/Users-Public-Keys#get-a-single-public-key
 func GetPublicKey(ctx *context.APIContext) {
+	// swagger:route GET /user/keys/{id} userCurrentGetKey
+	//
+	//     Produces:
+	//     - application/json
+	//
+	//     Responses:
+	//       200: PublicKey
+	//       404: notFound
+	//       500: error
+
 	key, err := models.GetPublicKeyByID(ctx.ParamsInt64(":id"))
 	if err != nil {
 		if models.IsErrKeyNotExist(err) {
@@ -104,14 +129,35 @@ func CreateUserPublicKey(ctx *context.APIContext, form api.CreateKeyOption, uid
 }
 
 // CreatePublicKey create one public key for me
-// see https://github.com/gogits/go-gogs-client/wiki/Users-Public-Keys#create-a-public-key
 func CreatePublicKey(ctx *context.APIContext, form api.CreateKeyOption) {
+	// swagger:route POST /user/keys userCurrentPostKey
+	//
+	//     Consumes:
+	//     - application/json
+	//
+	//     Produces:
+	//     - application/json
+	//
+	//     Responses:
+	//       201: PublicKey
+	//       422: validationError
+	//       500: error
+
 	CreateUserPublicKey(ctx, form, ctx.User.ID)
 }
 
 // DeletePublicKey delete one public key of mine
-// see https://github.com/gogits/go-gogs-client/wiki/Users-Public-Keys#delete-a-public-key
 func DeletePublicKey(ctx *context.APIContext) {
+	// swagger:route DELETE /user/keys/{id} userCurrentDeleteKey
+	//
+	//     Produces:
+	//     - application/json
+	//
+	//     Responses:
+	//       204: empty
+	//       403: forbidden
+	//       500: error
+
 	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 cc08094fc5..ddb932bce9 100644
--- a/routers/api/v1/user/repo.go
+++ b/routers/api/v1/user/repo.go
@@ -36,6 +36,15 @@ func listUserRepos(ctx *context.APIContext, u *models.User) {
 
 // ListUserRepos - list the repos owned and accessible by the given user.
 func ListUserRepos(ctx *context.APIContext) {
+	// swagger:route GET /users/{username}/repos userListRepos
+	//
+	//     Produces:
+	//     - application/json
+	//
+	//     Responses:
+	//       200: RepositoryList
+	//       500: error
+
 	user := GetUserByParams(ctx)
 	if ctx.Written() {
 		return
@@ -44,8 +53,16 @@ func ListUserRepos(ctx *context.APIContext) {
 }
 
 // ListMyRepos - list the repositories owned by you.
-// see https://github.com/gogits/go-gogs-client/wiki/Repositories#list-your-repositories
 func ListMyRepos(ctx *context.APIContext) {
+	// swagger:route GET /user/repos userCurrentListRepos
+	//
+	//     Produces:
+	//     - application/json
+	//
+	//     Responses:
+	//       200: RepositoryList
+	//       500: error
+
 	listUserRepos(ctx, ctx.User)
 }
 
diff --git a/routers/api/v1/user/star.go b/routers/api/v1/user/star.go
index 47d3ed5079..49d704cb2e 100644
--- a/routers/api/v1/user/star.go
+++ b/routers/api/v1/user/star.go
@@ -33,6 +33,15 @@ func getStarredRepos(userID int64, private bool) ([]*api.Repository, error) {
 // GetStarredRepos returns the repos that the user specified by the APIContext
 // has starred
 func GetStarredRepos(ctx *context.APIContext) {
+	// swagger:route GET /users/{username}/starred userListStarred
+	//
+	//     Produces:
+	//     - application/json
+	//
+	//     Responses:
+	//       200: RepositoryList
+	//       500: error
+
 	user := GetUserByParams(ctx)
 	private := user.ID == ctx.User.ID
 	repos, err := getStarredRepos(user.ID, private)
@@ -44,6 +53,15 @@ 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 userCurrentListStarred
+	//
+	//     Produces:
+	//     - application/json
+	//
+	//     Responses:
+	//       200: RepositoryList
+	//       500: error
+
 	repos, err := getStarredRepos(ctx.User.ID, true)
 	if err != nil {
 		ctx.Error(500, "getStarredRepos", err)
@@ -53,6 +71,12 @@ 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} userCurrentCheckStarring
+	//
+	//     Responses:
+	//       204: empty
+	//       404: notFound
+
 	if models.IsStaring(ctx.User.ID, ctx.Repo.Repository.ID) {
 		ctx.Status(204)
 	} else {
@@ -62,6 +86,12 @@ 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} userCurrentPutStar
+	//
+	//     Responses:
+	//       204: empty
+	//       500: error
+
 	err := models.StarRepo(ctx.User.ID, ctx.Repo.Repository.ID, true)
 	if err != nil {
 		ctx.Error(500, "StarRepo", err)
@@ -72,6 +102,12 @@ 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} userCurrentDeleteStar
+	//
+	//     Responses:
+	//       204: empty
+	//       500: error
+
 	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 de99fade46..cdb55c0d81 100644
--- a/routers/api/v1/user/user.go
+++ b/routers/api/v1/user/user.go
@@ -17,6 +17,15 @@ import (
 
 // Search search users
 func Search(ctx *context.APIContext) {
+	// swagger:route GET /users/search userSearch
+	//
+	//     Produces:
+	//     - application/json
+	//
+	//     Responses:
+	//       200: UserList
+	//       500: error
+
 	opts := &models.SearchUserOptions{
 		Keyword:  strings.Trim(ctx.Query("q"), " "),
 		Type:     models.UserTypeIndividual,
@@ -56,6 +65,16 @@ func Search(ctx *context.APIContext) {
 
 // GetInfo get user's information
 func GetInfo(ctx *context.APIContext) {
+	// swagger:route GET /users/{username} userGet
+	//
+	//     Produces:
+	//     - application/json
+	//
+	//     Responses:
+	//       200: User
+	//       404: notFound
+	//       500: error
+
 	u, err := models.GetUserByName(ctx.Params(":username"))
 	if err != nil {
 		if models.IsErrUserNotExist(err) {
@@ -75,5 +94,13 @@ func GetInfo(ctx *context.APIContext) {
 
 // GetAuthenticatedUser get curent user's information
 func GetAuthenticatedUser(ctx *context.APIContext) {
+	// swagger:route GET /user userGetCurrent
+	//
+	//     Produces:
+	//     - application/json
+	//
+	//     Responses:
+	//       200: User
+
 	ctx.JSON(200, ctx.User.APIFormat())
 }
diff --git a/routers/api/v1/user/watch.go b/routers/api/v1/user/watch.go
index 8bf4eeb505..230c819202 100644
--- a/routers/api/v1/user/watch.go
+++ b/routers/api/v1/user/watch.go
@@ -33,6 +33,15 @@ 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 userListSubscriptions
+	//
+	//     Produces:
+	//     - application/json
+	//
+	//     Responses:
+	//       200: RepositoryList
+	//       500: error
+
 	user := GetUserByParams(ctx)
 	private := user.ID == ctx.User.ID
 	repos, err := getWatchedRepos(user.ID, private)
@@ -44,6 +53,15 @@ 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 userCurrentListSubscriptions
+	//
+	//     Produces:
+	//     - application/json
+	//
+	//     Responses:
+	//       200: RepositoryList
+	//       500: error
+
 	repos, err := getWatchedRepos(ctx.User.ID, true)
 	if err != nil {
 		ctx.Error(500, "getWatchedRepos", err)
@@ -54,6 +72,12 @@ 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 userCurrentCheckSubscription
+	//
+	//     Responses:
+	//       200: WatchInfo
+	//       404: notFound
+
 	if models.IsWatching(ctx.User.ID, ctx.Repo.Repository.ID) {
 		ctx.JSON(200, api.WatchInfo{
 			Subscribed:    true,
@@ -70,6 +94,12 @@ 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 userCurrentPutSubscription
+	//
+	//     Responses:
+	//       200: WatchInfo
+	//       500: error
+
 	err := models.WatchRepo(ctx.User.ID, ctx.Repo.Repository.ID, true)
 	if err != nil {
 		ctx.Error(500, "WatchRepo", err)
@@ -88,6 +118,12 @@ 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 userCurrentDeleteSubscription
+	//
+	//     Responses:
+	//       204: empty
+	//       500: error
+
 	err := models.WatchRepo(ctx.User.ID, ctx.Repo.Repository.ID, false)
 	if err != nil {
 		ctx.Error(500, "UnwatchRepo", err)