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

44 files changed, 3270 insertions, 837 deletions

diff --git a/routers/api/v1/admin/org.go b/routers/api/v1/admin/org.go
index 99c9cf0b95..d247b51c72 100644
--- a/routers/api/v1/admin/org.go
+++ b/routers/api/v1/admin/org.go
@@ -15,20 +15,26 @@ import (
 
 // CreateOrg api for create organization
 func CreateOrg(ctx *context.APIContext, form api.CreateOrgOption) {
-	// swagger:route POST /admin/users/{username}/orgs admin adminCreateOrg
-	//
-	//     Consumes:
-	//     - application/json
-	//
-	//     Produces:
-	//     - application/json
-	//
-	//     Responses:
-	//       201: Organization
-	//       403: forbidden
-	//       422: validationError
-	//       500: error
-
+	// swagger:operation POST /admin/users/{username}/orgs admin adminCreateOrg
+	// ---
+	// summary: Create an organization
+	// consumes:
+	// - application/json
+	// produces:
+	// - application/json
+	// parameters:
+	// - name: username
+	//   in: path
+	//   description: username of the user that will own the created organization
+	//   type: string
+	//   required: true
+	// responses:
+	//   "201":
+	//     "$ref": "#/responses/Organization"
+	//   "403":
+	//     "$ref": "#/responses/forbidden"
+	//   "422":
+	//     "$ref": "#/responses/validationError"
 	u := user.GetUserByParams(ctx)
 	if ctx.Written() {
 		return
diff --git a/routers/api/v1/admin/repo.go b/routers/api/v1/admin/repo.go
index 232fb988c8..70765557fb 100644
--- a/routers/api/v1/admin/repo.go
+++ b/routers/api/v1/admin/repo.go
@@ -14,20 +14,26 @@ import (
 
 // CreateRepo api for creating a repository
 func CreateRepo(ctx *context.APIContext, form api.CreateRepoOption) {
-	// swagger:route POST /admin/users/{username}/repos admin adminCreateRepo
-	//
-	//     Consumes:
-	//     - application/json
-	//
-	//     Produces:
-	//     - application/json
-	//
-	//     Responses:
-	//       201: Repository
-	//       403: forbidden
-	//       422: validationError
-	//       500: error
-
+	// swagger:operation POST /admin/users/{username}/repos admin adminCreateRepo
+	// ---
+	// summary: Create a repository on behalf a user
+	// consumes:
+	// - application/json
+	// produces:
+	// - application/json
+	// parameters:
+	// - name: username
+	//   in: path
+	//   description: username of the user. This user will own the created repository
+	//   type: string
+	//   required: true
+	// responses:
+	//   "201":
+	//     "$ref": "#/responses/Repository"
+	//   "403":
+	//     "$ref": "#/responses/forbidden"
+	//   "422":
+	//     "$ref": "#/responses/validationError"
 	owner := user.GetUserByParams(ctx)
 	if ctx.Written() {
 		return
diff --git a/routers/api/v1/admin/user.go b/routers/api/v1/admin/user.go
index 74cbba8cde..19f24aed8f 100644
--- a/routers/api/v1/admin/user.go
+++ b/routers/api/v1/admin/user.go
@@ -5,13 +5,12 @@
 package admin
 
 import (
-	api "code.gitea.io/sdk/gitea"
-
 	"code.gitea.io/gitea/models"
 	"code.gitea.io/gitea/modules/context"
 	"code.gitea.io/gitea/modules/log"
 	"code.gitea.io/gitea/modules/setting"
 	"code.gitea.io/gitea/routers/api/v1/user"
+	api "code.gitea.io/sdk/gitea"
 )
 
 func parseLoginSource(ctx *context.APIContext, u *models.User, sourceID int64, loginName string) {
@@ -34,22 +33,27 @@ func parseLoginSource(ctx *context.APIContext, u *models.User, sourceID int64, l
 	u.LoginName = loginName
 }
 
-// CreateUser api for creating a user
+// CreateUser create a user
 func CreateUser(ctx *context.APIContext, form api.CreateUserOption) {
-	// swagger:route POST /admin/users admin adminCreateUser
-	//
-	//     Consumes:
-	//     - application/json
-	//
-	//     Produces:
-	//     - application/json
-	//
-	//     Responses:
-	//       201: User
-	//       403: forbidden
-	//       422: validationError
-	//       500: error
-
+	// swagger:operation POST /admin/users admin adminCreateUser
+	// ---
+	// summary: Create a user
+	// consumes:
+	// - application/json
+	// produces:
+	// - application/json
+	// parameters:
+	// - name: body
+	//   in: body
+	//   schema:
+	//     "$ref": "#/definitions/CreateUserOption"
+	// responses:
+	//   "201":
+	//     "$ref": "#/responses/User"
+	//   "403":
+	//     "$ref": "#/responses/forbidden"
+	//   "422":
+	//     "$ref": "#/responses/validationError"
 	u := &models.User{
 		Name:      form.Username,
 		FullName:  form.FullName,
@@ -87,20 +91,30 @@ func CreateUser(ctx *context.APIContext, form api.CreateUserOption) {
 
 // EditUser api for modifying a user's information
 func EditUser(ctx *context.APIContext, form api.EditUserOption) {
-	// swagger:route PATCH /admin/users/{username} admin adminEditUser
-	//
-	//     Consumes:
-	//     - application/json
-	//
-	//     Produces:
-	//     - application/json
-	//
-	//     Responses:
-	//       200: User
-	//       403: forbidden
-	//       422: validationError
-	//       500: error
-
+	// swagger:operation PATCH /admin/users/{username} admin adminEditUser
+	// ---
+	// summary: Edit an existing user
+	// consumes:
+	// - application/json
+	// produces:
+	// - application/json
+	// parameters:
+	// - name: username
+	//   in: path
+	//   description: username of user to edit
+	//   type: string
+	//   required: true
+	// - name: body
+	//   in: body
+	//   schema:
+	//     "$ref": "#/definitions/EditUserOption"
+	// responses:
+	//   "200":
+	//     "$ref": "#/responses/User"
+	//   "403":
+	//     "$ref": "#/responses/forbidden"
+	//   "422":
+	//     "$ref": "#/responses/validationError"
 	u := user.GetUserByParams(ctx)
 	if ctx.Written() {
 		return
@@ -157,17 +171,24 @@ func EditUser(ctx *context.APIContext, form api.EditUserOption) {
 
 // DeleteUser api for deleting a user
 func DeleteUser(ctx *context.APIContext) {
-	// swagger:route DELETE /admin/users/{username} admin adminDeleteUser
-	//
-	//     Produces:
-	//     - application/json
-	//
-	//     Responses:
-	//       204: empty
-	//       403: forbidden
-	//       422: validationError
-	//       500: error
-
+	// swagger:operation DELETE /admin/users/{username} admin adminDeleteUser
+	// ---
+	// summary: Delete a user
+	// produces:
+	// - application/json
+	// parameters:
+	// - name: username
+	//   in: path
+	//   description: username of user to delete
+	//   type: string
+	//   required: true
+	// responses:
+	//   "204":
+	//     "$ref": "#/responses/empty"
+	//   "403":
+	//     "$ref": "#/responses/forbidden"
+	//   "422":
+	//     "$ref": "#/responses/validationError"
 	u := user.GetUserByParams(ctx)
 	if ctx.Written() {
 		return
@@ -189,20 +210,26 @@ func DeleteUser(ctx *context.APIContext) {
 
 // CreatePublicKey api for creating a public key to a user
 func CreatePublicKey(ctx *context.APIContext, form api.CreateKeyOption) {
-	// swagger:route POST /admin/users/{username}/keys admin adminCreatePublicKey
-	//
-	//     Consumes:
-	//     - application/json
-	//
-	//     Produces:
-	//     - application/json
-	//
-	//     Responses:
-	//       201: PublicKey
-	//       403: forbidden
-	//       422: validationError
-	//       500: error
-
+	// swagger:operation POST /admin/users/{username}/keys admin adminCreatePublicKey
+	// ---
+	// summary: Add a public key on behalf of a user
+	// consumes:
+	// - application/json
+	// produces:
+	// - application/json
+	// parameters:
+	// - name: username
+	//   in: path
+	//   description: username of the user
+	//   type: string
+	//   required: true
+	// responses:
+	//   "201":
+	//     "$ref": "#/responses/PublicKey"
+	//   "403":
+	//     "$ref": "#/responses/forbidden"
+	//   "422":
+	//     "$ref": "#/responses/validationError"
 	u := user.GetUserByParams(ctx)
 	if ctx.Written() {
 		return
diff --git a/routers/api/v1/api.go b/routers/api/v1/api.go
index 4331929614..b6e7df1215 100644
--- a/routers/api/v1/api.go
+++ b/routers/api/v1/api.go
@@ -4,11 +4,7 @@
 
 // Package v1 Gitea API.
 //
-// This provide API interface to communicate with this Gitea instance.
-//
-// Terms Of Service:
-//
-// there are no TOS at this moment, use at your own risk we take no responsibility
+// This documentation describes the Gitea API.
 //
 //     Schemes: http, https
 //     BasePath: /api/v1
@@ -51,11 +47,6 @@ package v1
 import (
 	"strings"
 
-	"github.com/go-macaron/binding"
-	"gopkg.in/macaron.v1"
-
-	api "code.gitea.io/sdk/gitea"
-
 	"code.gitea.io/gitea/models"
 	"code.gitea.io/gitea/modules/auth"
 	"code.gitea.io/gitea/modules/context"
@@ -63,8 +54,13 @@ import (
 	"code.gitea.io/gitea/routers/api/v1/misc"
 	"code.gitea.io/gitea/routers/api/v1/org"
 	"code.gitea.io/gitea/routers/api/v1/repo"
+	_ "code.gitea.io/gitea/routers/api/v1/swagger" // for swagger generation
 	"code.gitea.io/gitea/routers/api/v1/user"
 	"code.gitea.io/gitea/routers/api/v1/utils"
+	api "code.gitea.io/sdk/gitea"
+
+	"github.com/go-macaron/binding"
+	"gopkg.in/macaron.v1"
 )
 
 func repoAssignment() macaron.Handler {
@@ -320,7 +316,7 @@ func RegisterRoutes(m *macaron.Macaron) {
 			m.Get("", user.GetAuthenticatedUser)
 			m.Combo("/emails").Get(user.ListEmails).
 				Post(bind(api.CreateEmailOption{}), user.AddEmail).
-				Delete(bind(api.CreateEmailOption{}), user.DeleteEmail)
+				Delete(bind(api.DeleteEmailOption{}), user.DeleteEmail)
 
 			m.Get("/followers", user.ListMyFollowers)
 			m.Group("/following", func() {
@@ -435,7 +431,6 @@ func RegisterRoutes(m *macaron.Macaron) {
 							m.Combo("").Get(repo.ListTrackedTimes).
 								Post(reqToken(), bind(api.AddTimeOption{}), repo.AddTime)
 						})
-
 					})
 				}, mustEnableIssues)
 				m.Group("/labels", func() {
@@ -484,8 +479,8 @@ func RegisterRoutes(m *macaron.Macaron) {
 						Post(reqToken(), reqRepoWriter(), bind(api.CreateStatusOption{}), repo.NewCommitStatus)
 				})
 				m.Group("/commits/:ref", func() {
-					m.Get("/status", repo.GetCombinedCommitStatus)
-					m.Get("/statuses", repo.GetCommitStatuses)
+					m.Get("/status", repo.GetCombinedCommitStatusByRef)
+					m.Get("/statuses", repo.GetCommitStatusesByRef)
 				})
 			}, repoAssignment())
 		})
diff --git a/routers/api/v1/misc/markdown.go b/routers/api/v1/misc/markdown.go
index 8e3c66841f..ed50c1c05b 100644
--- a/routers/api/v1/misc/markdown.go
+++ b/routers/api/v1/misc/markdown.go
@@ -15,18 +15,23 @@ import (
 
 // Markdown render markdown document to HTML
 func Markdown(ctx *context.APIContext, form api.MarkdownOption) {
-	// swagger:route POST /markdown miscellaneous renderMarkdown
-	//
-	//     Consumes:
-	//     - application/json
-	//
-	//     Produces:
+	// swagger:operation POST /markdown miscellaneous renderMarkdown
+	// ---
+	// summary: Render a markdown document as HTML
+	// parameters:
+	// - name: body
+	//   in: body
+	//   schema:
+	//     "$ref": "#/definitions/MarkdownOption"
+	// consumes:
+	// - application/json
+	// produces:
 	//     - text/html
-	//
-	//     Responses:
-	//       200: MarkdownRender
-	//       422: validationError
-
+	// responses:
+	//   "200":
+	//     "$ref": "#/responses/MarkdownRender"
+	//   "422":
+	//     "$ref": "#/responses/validationError"
 	if ctx.HasAPIError() {
 		ctx.Error(422, "", ctx.GetErrMsg())
 		return
@@ -53,17 +58,22 @@ func Markdown(ctx *context.APIContext, form api.MarkdownOption) {
 
 // MarkdownRaw render raw markdown HTML
 func MarkdownRaw(ctx *context.APIContext) {
-	// swagger:route POST /markdown/raw miscellaneous renderMarkdownRaw
-	//
-	//     Consumes:
+	// swagger:operation POST /markdown/raw miscellaneous renderMarkdownRaw
+	// ---
+	// summary: Render raw markdown as HTML
+	// parameters:
+	// - name: body
+	//   in: body
+	//   type: string
+	// consumes:
 	//     - text/plain
-	//
-	//     Produces:
+	// produces:
 	//     - text/html
-	//
-	//     Responses:
-	//       200: MarkdownRender
-	//       422: validationError
+	// responses:
+	//   "200":
+	//     "$ref": "#/responses/MarkdownRender"
+	//   "422":
+	//     "$ref": "#/responses/validationError"
 	body, err := ctx.Req.Body().Bytes()
 	if err != nil {
 		ctx.Error(422, "", err)
diff --git a/routers/api/v1/misc/version.go b/routers/api/v1/misc/version.go
index 1780398bf9..20e0a60c72 100644
--- a/routers/api/v1/misc/version.go
+++ b/routers/api/v1/misc/version.go
@@ -12,17 +12,13 @@ import (
 
 // Version shows the version of the Gitea server
 func Version(ctx *context.APIContext) {
-	// swagger:route GET /version miscellaneous getVersion
-	//
-	// Return Gitea running version.
-	//
-	// This show current running Gitea application version.
-	//
-	//     Produces:
-	//     - application/json
-	//
-	//     Responses:
-	//       200: ServerVersion
-
+	// swagger:operation GET /version miscellaneous getVersion
+	// ---
+	// summary: Returns the version of the Gitea application
+	// produces:
+	// - application/json
+	// responses:
+	//   "200":
+	//     "$ref": "#/responses/ServerVersion"
 	ctx.JSON(200, &gitea.ServerVersion{Version: setting.AppVer})
 }
diff --git a/routers/api/v1/org/hook.go b/routers/api/v1/org/hook.go
index d8a4c45fc8..0a77d795e6 100644
--- a/routers/api/v1/org/hook.go
+++ b/routers/api/v1/org/hook.go
@@ -15,15 +15,14 @@ import (
 
 // ListHooks list an organziation's webhooks
 func ListHooks(ctx *context.APIContext) {
-	// swagger:route GET /orgs/{orgname}/hooks organization orgListHooks
-	//
-	//     Produces:
-	//     - application/json
-	//
-	//     Responses:
-	//       200: HookList
-	//       500: error
-
+	// swagger:operation GET /orgs/{org}/hooks organization orgListHooks
+	// ---
+	// summary: List an organization's webhooks
+	// produces:
+	// - application/json
+	// responses:
+	//   "200":
+	//     "$ref": "#/responses/HookList"
 	org := ctx.Org.Organization
 	orgHooks, err := models.GetWebhooksByOrgID(org.ID)
 	if err != nil {
@@ -39,16 +38,14 @@ func ListHooks(ctx *context.APIContext) {
 
 // GetHook get an organization's hook by id
 func GetHook(ctx *context.APIContext) {
-	// swagger:route GET /orgs/{orgname}/hooks/{id} organization orgGetHook
-	//
-	//     Produces:
-	//     - application/json
-	//
-	//     Responses:
-	//       200: Hook
-	//       404: notFound
-	//       500: error
-
+	// swagger:operation GET /orgs/{org}/hooks/{id} organization orgGetHook
+	// ---
+	// summary: Get a hook
+	// produces:
+	// - application/json
+	// responses:
+	//   "200":
+	//     "$ref": "#/responses/Hook"
 	org := ctx.Org.Organization
 	hookID := ctx.ParamsInt64(":id")
 	hook, err := utils.GetOrgHook(ctx, org.ID, hookID)
@@ -60,19 +57,16 @@ func GetHook(ctx *context.APIContext) {
 
 // CreateHook create a hook for an organization
 func CreateHook(ctx *context.APIContext, form api.CreateHookOption) {
-	// swagger:route POST /orgs/{orgname}/hooks/ organization orgCreateHook
-	//
-	//     Consumes:
-	//     - application/json
-	//
-	//     Produces:
-	//     - application/json
-	//
-	//     Responses:
-	//       201: Hook
-	//       422: validationError
-	//       500: error
-
+	// swagger:operation POST /orgs/{org}/hooks/ organization orgCreateHook
+	// ---
+	// summary: Create a hook
+	// consumes:
+	// - application/json
+	// produces:
+	// - application/json
+	// responses:
+	//   "201":
+	//     "$ref": "#/responses/Hook"
 	if !utils.CheckCreateHookOption(ctx, &form) {
 		return
 	}
@@ -81,36 +75,30 @@ func CreateHook(ctx *context.APIContext, form api.CreateHookOption) {
 
 // EditHook modify a hook of a repository
 func EditHook(ctx *context.APIContext, form api.EditHookOption) {
-	// swagger:route PATCH /orgs/{orgname}/hooks/{id} organization orgEditHook
-	//
-	//     Consumes:
-	//     - application/json
-	//
-	//     Produces:
-	//     - application/json
-	//
-	//     Responses:
-	//       200: Hook
-	//       422: validationError
-	//       404: notFound
-	//       500: error
-
+	// swagger:operation PATCH /orgs/{org}/hooks/{id} organization orgEditHook
+	// ---
+	// summary: Update a hook
+	// consumes:
+	// - application/json
+	// produces:
+	// - application/json
+	// responses:
+	//   "200":
+	//     "$ref": "#/responses/Hook"
 	hookID := ctx.ParamsInt64(":id")
 	utils.EditOrgHook(ctx, &form, hookID)
 }
 
 // DeleteHook delete a hook of an organization
 func DeleteHook(ctx *context.APIContext) {
-	// swagger:route DELETE /orgs/{orgname}/hooks/{id} organization orgDeleteHook
-	//
-	//     Produces:
-	//     - application/json
-	//
-	//     Responses:
-	//       204: empty
-	//       404: notFound
-	//       500: error
-
+	// swagger:operation DELETE /orgs/{org}/hooks/{id} organization orgDeleteHook
+	// ---
+	// summary: Delete a hook
+	// produces:
+	// - application/json
+	// responses:
+	//   "204":
+	//     "$ref": "#/responses/empty"
 	org := ctx.Org.Organization
 	hookID := ctx.ParamsInt64(":id")
 	if err := models.DeleteWebhookByOrgID(org.ID, hookID); err != nil {
diff --git a/routers/api/v1/org/member.go b/routers/api/v1/org/member.go
index 3495370556..7cae7c19fa 100644
--- a/routers/api/v1/org/member.go
+++ b/routers/api/v1/org/member.go
@@ -53,45 +53,68 @@ func listMembers(ctx *context.APIContext, publicOnly bool) {
 
 // ListMembers list an organization's members
 func ListMembers(ctx *context.APIContext) {
-	// swagger:route GET /orgs/{orgname}/members organization orgListMembers
-	//
-	//     Produces:
-	//     - application/json
-	//
-	//     Responses:
-	//       200: UserList
-	//       500: error
-
+	// swagger:operation GET /orgs/{org}/members organization orgListMembers
+	// ---
+	// summary: List an organization's members
+	// produces:
+	// - application/json
+	// parameters:
+	// - name: org
+	//   in: path
+	//   description: name of the organization
+	//   type: string
+	//   required: true
+	// responses:
+	//   "200":
+	//     "$ref": "#/responses/UserList"
 	publicOnly := ctx.User == nil || !ctx.Org.Organization.IsOrgMember(ctx.User.ID)
 	listMembers(ctx, publicOnly)
 }
 
 // ListPublicMembers list an organization's public members
 func ListPublicMembers(ctx *context.APIContext) {
-	// swagger:route GET /orgs/{orgname}/public_members organization orgListPublicMembers
-	//
-	//     Produces:
-	//     - application/json
-	//
-	//     Responses:
-	//       200: UserList
-	//       500: error
-
+	// swagger:operation GET /orgs/{org}/public_members organization orgListPublicMembers
+	// ---
+	// summary: List an organization's public members
+	// parameters:
+	// - name: org
+	//   in: path
+	//   description: name of the organization
+	//   type: string
+	//   required: true
+	// produces:
+	// - application/json
+	// responses:
+	//   "200":
+	//     "$ref": "#/responses/UserList"
 	listMembers(ctx, true)
 }
 
 // IsMember check if a user is a member of an organization
 func IsMember(ctx *context.APIContext) {
-	// swagger:route GET /orgs/{orgname}/members/{username} organization orgIsMember
-	//
-	//     Produces:
-	//     - application/json
-	//
-	//     Responses:
-	//       204: empty
-	//       302: redirect
-	//       404: notFound
-
+	// swagger:operation GET /orgs/{org}/members/{username} organization orgIsMember
+	// ---
+	// summary: Check if a user is a member of an organization
+	// parameters:
+	// - name: org
+	//   in: path
+	//   description: name of the organization
+	//   type: string
+	//   required: true
+	// - name: username
+	//   in: path
+	//   description: username of the user
+	//   type: string
+	//   required: true
+	// responses:
+	//   "204":
+	//     description: user is a member
+	//     schema:
+	//       "$ref": "#/responses/empty"
+	//   "404":
+	//     description: user is not a member
+	//     schema:
+	//       "$ref": "#/responses/empty"
 	userToCheck := user.GetUserByParams(ctx)
 	if ctx.Written() {
 		return
@@ -113,15 +136,29 @@ func IsMember(ctx *context.APIContext) {
 
 // IsPublicMember check if a user is a public member of an organization
 func IsPublicMember(ctx *context.APIContext) {
-	// swagger:route GET /orgs/{orgname}/public_members/{username} organization orgIsPublicMember
-	//
-	//     Produces:
-	//     - application/json
-	//
-	//     Responses:
-	//       204: empty
-	//       404: notFound
-
+	// swagger:operation GET /orgs/{org}/public_members/{username} organization orgIsPublicMember
+	// ---
+	// summary: Check if a user is a public member of an organization
+	// parameters:
+	// - name: org
+	//   in: path
+	//   description: name of the organization
+	//   type: string
+	//   required: true
+	// - name: username
+	//   in: path
+	//   description: username of the user
+	//   type: string
+	//   required: true
+	// responses:
+	//   "204":
+	//     description: user is a public member
+	//     schema:
+	//       "$ref": "#/responses/empty"
+	//   "404":
+	//     description: user is not a public member
+	//     schema:
+	//       "$ref": "#/responses/empty"
 	userToCheck := user.GetUserByParams(ctx)
 	if ctx.Written() {
 		return
@@ -135,16 +172,27 @@ func IsPublicMember(ctx *context.APIContext) {
 
 // PublicizeMember make a member's membership public
 func PublicizeMember(ctx *context.APIContext) {
-	// swagger:route PUT /orgs/{orgname}/public_members/{username} organization orgPublicizeMember
-	//
-	//     Produces:
-	//     - application/json
-	//
-	//     Responses:
-	//       204: empty
-	//       403: forbidden
-	//       500: error
-
+	// swagger:operation PUT /orgs/{org}/public_members/{username} organization orgPublicizeMember
+	// ---
+	// summary: Publicize a user's membership
+	// produces:
+	// - application/json
+	// parameters:
+	// - name: org
+	//   in: path
+	//   description: name of the organization
+	//   type: string
+	//   required: true
+	// - name: username
+	//   in: path
+	//   description: username of the user
+	//   type: string
+	//   required: true
+	// responses:
+	//   "204":
+	//     description: membership publicized
+	//     schema:
+	//       "$ref": "#/responses/empty"
 	userToPublicize := user.GetUserByParams(ctx)
 	if ctx.Written() {
 		return
@@ -163,16 +211,25 @@ func PublicizeMember(ctx *context.APIContext) {
 
 // ConcealMember make a member's membership not public
 func ConcealMember(ctx *context.APIContext) {
-	// swagger:route DELETE /orgs/{orgname}/public_members/{username} organization orgConcealMember
-	//
-	//     Produces:
-	//     - application/json
-	//
-	//     Responses:
-	//       204: empty
-	//       403: forbidden
-	//       500: error
-
+	// swagger:operation DELETE /orgs/{org}/public_members/{username} organization orgConcealMember
+	// ---
+	// summary: Conceal a user's membership
+	// produces:
+	// - application/json
+	// parameters:
+	// - name: org
+	//   in: path
+	//   description: name of the organization
+	//   type: string
+	//   required: true
+	// - name: username
+	//   in: path
+	//   description: username of the user
+	//   type: string
+	//   required: true
+	// responses:
+	//   "204":
+	//     "$ref": "#/responses/empty"
 	userToConceal := user.GetUserByParams(ctx)
 	if ctx.Written() {
 		return
@@ -191,15 +248,27 @@ func ConcealMember(ctx *context.APIContext) {
 
 // DeleteMember remove a member from an organization
 func DeleteMember(ctx *context.APIContext) {
-	// swagger:route DELETE /orgs/{orgname}/members/{username} organization orgDeleteMember
-	//
-	//     Produces:
-	//     - application/json
-	//
-	//     Responses:
-	//       204: empty
-	//       500: error
-
+	// swagger:operation DELETE /orgs/{org}/members/{username} organization orgDeleteMember
+	// ---
+	// summary: Remove a member from an organization
+	// produces:
+	// - application/json
+	// parameters:
+	// - name: org
+	//   in: path
+	//   description: name of the organization
+	//   type: string
+	//   required: true
+	// - name: username
+	//   in: path
+	//   description: username of the user
+	//   type: string
+	//   required: true
+	// responses:
+	//   "204":
+	//     description: member removed
+	//     schema:
+	//       "$ref": "#/responses/empty"
 	member := user.GetUserByParams(ctx)
 	if ctx.Written() {
 		return
diff --git a/routers/api/v1/org/org.go b/routers/api/v1/org/org.go
index ec55b9ebe4..c24a4aeb10 100644
--- a/routers/api/v1/org/org.go
+++ b/routers/api/v1/org/org.go
@@ -27,14 +27,33 @@ func listUserOrgs(ctx *context.APIContext, u *models.User, all bool) {
 }
 
 // ListMyOrgs list all my orgs
-// see https://github.com/gogits/go-gogs-client/wiki/Organizations#list-your-organizations
 func ListMyOrgs(ctx *context.APIContext) {
+	// swagger:operation GET /user/orgs organization orgListCurrentUserOrgs
+	// ---
+	// summary: List the current user's organizations
+	// produces:
+	// - application/json
+	// responses:
+	//   "200":
+	//     "$ref": "#/responses/OrganizationList"
 	listUserOrgs(ctx, ctx.User, true)
 }
 
 // ListUserOrgs list user's orgs
-// see https://github.com/gogits/go-gogs-client/wiki/Organizations#list-user-organizations
 func ListUserOrgs(ctx *context.APIContext) {
+	// swagger:operation GET /user/{username}/orgs organization orgListUserOrgs
+	// ---
+	// summary: List a user's organizations
+	// produces:
+	// - application/json
+	// parameters:
+	// - name: username
+	//   in: path
+	//   description: username of user
+	//   type: string
+	// responses:
+	//   "200":
+	//     "$ref": "#/responses/OrganizationList"
 	u := user.GetUserByParams(ctx)
 	if ctx.Written() {
 		return
@@ -43,14 +62,46 @@ func ListUserOrgs(ctx *context.APIContext) {
 }
 
 // Get get an organization
-// see https://github.com/gogits/go-gogs-client/wiki/Organizations#get-an-organization
 func Get(ctx *context.APIContext) {
+	// swagger:operation GET /orgs/{org} organization orgGet
+	// ---
+	// summary: Get an organization
+	// produces:
+	// - application/json
+	// parameters:
+	// - name: org
+	//   in: path
+	//   description: name of the organization to get
+	//   type: string
+	//   required: true
+	// responses:
+	//   "200":
+	//     "$ref": "#/responses/Organization"
 	ctx.JSON(200, convert.ToOrganization(ctx.Org.Organization))
 }
 
 // Edit change an organization's information
-// see https://github.com/gogits/go-gogs-client/wiki/Organizations#edit-an-organization
 func Edit(ctx *context.APIContext, form api.EditOrgOption) {
+	// swagger:operation PATCH /orgs/{org} organization orgEdit
+	// ---
+	// summary: Edit an organization
+	// consumes:
+	// - application/json
+	// produces:
+	// - application/json
+	// parameters:
+	// - name: org
+	//   in: path
+	//   description: name of the organization to edit
+	//   type: string
+	//   required: true
+	// - name: body
+	//   in: body
+	//   schema:
+	//     "$ref": "#/definitions/EditOrgOption"
+	// responses:
+	//   "200":
+	//     "$ref": "#/responses/Organization"
 	org := ctx.Org.Organization
 	org.FullName = form.FullName
 	org.Description = form.Description
diff --git a/routers/api/v1/org/team.go b/routers/api/v1/org/team.go
index dbd6ccc460..eead7dd8fd 100644
--- a/routers/api/v1/org/team.go
+++ b/routers/api/v1/org/team.go
@@ -15,6 +15,20 @@ import (
 
 // ListTeams list all the teams of an organization
 func ListTeams(ctx *context.APIContext) {
+	// swagger:operation GET /orgs/{org}/teams organization orgListTeams
+	// ---
+	// summary: List an organization's teams
+	// produces:
+	// - application/json
+	// parameters:
+	// - name: org
+	//   in: path
+	//   description: name of the organization
+	//   type: string
+	//   required: true
+	// responses:
+	//   "200":
+	//     "$ref": "#/responses/TeamList"
 	org := ctx.Org.Organization
 	if err := org.GetTeams(); err != nil {
 		ctx.Error(500, "GetTeams", err)
@@ -30,11 +44,45 @@ func ListTeams(ctx *context.APIContext) {
 
 // GetTeam api for get a team
 func GetTeam(ctx *context.APIContext) {
+	// swagger:operation GET /teams/{id} organization orgGetTeam
+	// ---
+	// summary: Get a team
+	// produces:
+	// - application/json
+	// parameters:
+	// - name: id
+	//   in: path
+	//   description: id of the team to get
+	//   type: integer
+	//   required: true
+	// responses:
+	//   "200":
+	//     "$ref": "#/responses/Team"
 	ctx.JSON(200, convert.ToTeam(ctx.Org.Team))
 }
 
 // CreateTeam api for create a team
 func CreateTeam(ctx *context.APIContext, form api.CreateTeamOption) {
+	// swagger:operation POST /orgs/{org}/teams organization orgCreateTeam
+	// ---
+	// summary: Create a team
+	// consumes:
+	// - application/json
+	// produces:
+	// - application/json
+	// parameters:
+	// - name: org
+	//   in: path
+	//   description: name of the organization
+	//   type: string
+	//   required: true
+	// - name: body
+	//   in: body
+	//   schema:
+	//     "$ref": "#/definitions/CreateTeamOption"
+	// responses:
+	//   "201":
+	//     "$ref": "#/responses/Team"
 	team := &models.Team{
 		OrgID:       ctx.Org.Organization.ID,
 		Name:        form.Name,
@@ -55,6 +103,26 @@ func CreateTeam(ctx *context.APIContext, form api.CreateTeamOption) {
 
 // EditTeam api for edit a team
 func EditTeam(ctx *context.APIContext, form api.EditTeamOption) {
+	// swagger:operation PATCH /teams/{id} organization orgEditTeam
+	// ---
+	// summary: Edit a team
+	// consumes:
+	// - application/json
+	// produces:
+	// - application/json
+	// parameters:
+	// - name: id
+	//   in: path
+	//   description: id of the team to edit
+	//   type: integer
+	//   required: true
+	// - name: body
+	//   in: body
+	//   schema:
+	//     "$ref": "#/definitions/EditTeamOption"
+	// responses:
+	//   "200":
+	//     "$ref": "#/responses/Team"
 	team := &models.Team{
 		ID:          ctx.Org.Team.ID,
 		OrgID:       ctx.Org.Team.OrgID,
@@ -71,6 +139,20 @@ func EditTeam(ctx *context.APIContext, form api.EditTeamOption) {
 
 // DeleteTeam api for delete a team
 func DeleteTeam(ctx *context.APIContext) {
+	// swagger:operation DELETE /teams/{id} organization orgDeleteTeam
+	// ---
+	// summary: Delete a team
+	// parameters:
+	// - name: id
+	//   in: path
+	//   description: id of the team to delete
+	//   type: integer
+	//   required: true
+	// responses:
+	//   "204":
+	//     description: team deleted
+	//     schema:
+	//       "$ref": "#/responses/empty"
 	if err := models.DeleteTeam(ctx.Org.Team); err != nil {
 		ctx.Error(500, "DeleteTeam", err)
 		return
@@ -80,6 +162,20 @@ func DeleteTeam(ctx *context.APIContext) {
 
 // GetTeamMembers api for get a team's members
 func GetTeamMembers(ctx *context.APIContext) {
+	// swagger:operation GET /teams/{id}/members organization orgListTeamMembers
+	// ---
+	// summary: List a team's members
+	// produces:
+	// - application/json
+	// parameters:
+	// - name: id
+	//   in: path
+	//   description: id of the team
+	//   type: integer
+	//   required: true
+	// responses:
+	//   "200":
+	//     "$ref": "#/responses/UserList"
 	if !models.IsOrganizationMember(ctx.Org.Team.OrgID, ctx.User.ID) {
 		ctx.Status(404)
 		return
@@ -98,6 +194,25 @@ func GetTeamMembers(ctx *context.APIContext) {
 
 // AddTeamMember api for add a member to a team
 func AddTeamMember(ctx *context.APIContext) {
+	// swagger:operation PUT /teams/{id}/members/{username} organization orgAddTeamMember
+	// ---
+	// summary: Add a team member
+	// produces:
+	// - application/json
+	// parameters:
+	// - name: id
+	//   in: path
+	//   description: id of the team
+	//   type: integer
+	//   required: true
+	// - name: username
+	//   in: path
+	//   description: username of the user to add
+	//   type: string
+	//   required: true
+	// responses:
+	//   "204":
+	//     "$ref": "#/responses/empty"
 	u := user.GetUserByParams(ctx)
 	if ctx.Written() {
 		return
@@ -111,6 +226,25 @@ func AddTeamMember(ctx *context.APIContext) {
 
 // RemoveTeamMember api for remove one member from a team
 func RemoveTeamMember(ctx *context.APIContext) {
+	// swagger:operation DELETE /teams/{id}/members/{username} organization orgAddTeamMember
+	// ---
+	// summary: Remove a team member
+	// produces:
+	// - application/json
+	// parameters:
+	// - name: id
+	//   in: path
+	//   description: id of the team
+	//   type: integer
+	//   required: true
+	// - name: username
+	//   in: path
+	//   description: username of the user to remove
+	//   type: string
+	//   required: true
+	// responses:
+	//   "204":
+	//     "$ref": "#/responses/empty"
 	u := user.GetUserByParams(ctx)
 	if ctx.Written() {
 		return
@@ -125,6 +259,20 @@ func RemoveTeamMember(ctx *context.APIContext) {
 
 // GetTeamRepos api for get a team's repos
 func GetTeamRepos(ctx *context.APIContext) {
+	// swagger:operation GET /teams/{id}/repos organization orgListTeamRepos
+	// ---
+	// summary: List a team's repos
+	// produces:
+	// - application/json
+	// parameters:
+	// - name: id
+	//   in: path
+	//   description: id of the team
+	//   type: integer
+	//   required: true
+	// responses:
+	//   "200":
+	//     "$ref": "#/responses/RepositoryList"
 	team := ctx.Org.Team
 	if err := team.GetRepositories(); err != nil {
 		ctx.Error(500, "GetTeamRepos", err)
@@ -157,6 +305,30 @@ func getRepositoryByParams(ctx *context.APIContext) *models.Repository {
 
 // AddTeamRepository api for adding a repository to a team
 func AddTeamRepository(ctx *context.APIContext) {
+	// swagger:operation PUT /teams/{id}/repos/{org}/{repo} organization orgAddTeamMember
+	// ---
+	// summary: Add a repository to a team
+	// produces:
+	// - application/json
+	// parameters:
+	// - name: id
+	//   in: path
+	//   description: id of the team
+	//   type: integer
+	//   required: true
+	// - name: org
+	//   in: path
+	//   description: organization that owns the repo to add
+	//   type: string
+	//   required: true
+	// - name: repo
+	//   in: path
+	//   description: name of the repo to add
+	//   type: string
+	//   required: true
+	// responses:
+	//   "204":
+	//     "$ref": "#/responses/empty"
 	repo := getRepositoryByParams(ctx)
 	if ctx.Written() {
 		return
@@ -177,6 +349,32 @@ func AddTeamRepository(ctx *context.APIContext) {
 
 // RemoveTeamRepository api for removing a repository from a team
 func RemoveTeamRepository(ctx *context.APIContext) {
+	// swagger:operation DELETE /teams/{id}/repos/{org}/{repo} organization orgAddTeamMember
+	// ---
+	// summary: Remove a repository from a team
+	// description: This does not delete the repository, it only removes the
+	//              repository from the team.
+	// produces:
+	// - application/json
+	// parameters:
+	// - name: id
+	//   in: path
+	//   description: id of the team
+	//   type: integer
+	//   required: true
+	// - name: org
+	//   in: path
+	//   description: organization that owns the repo to remove
+	//   type: string
+	//   required: true
+	// - name: repo
+	//   in: path
+	//   description: name of the repo to remove
+	//   type: string
+	//   required: true
+	// responses:
+	//   "204":
+	//     "$ref": "#/responses/empty"
 	repo := getRepositoryByParams(ctx)
 	if ctx.Written() {
 		return
diff --git a/routers/api/v1/repo/branch.go b/routers/api/v1/repo/branch.go
index aed630f558..a82527e6a7 100644
--- a/routers/api/v1/repo/branch.go
+++ b/routers/api/v1/repo/branch.go
@@ -13,8 +13,31 @@ import (
 )
 
 // GetBranch get a branch of a repository
-// see https://github.com/gogits/go-gogs-client/wiki/Repositories#get-branch
 func GetBranch(ctx *context.APIContext) {
+	// swagger:operation GET /repos/{owner}/{repo}/branches/{branch} repository repoGetBranch
+	// ---
+	// summary: List a repository's branches
+	// produces:
+	// - application/json
+	// parameters:
+	// - name: owner
+	//   in: path
+	//   description: owner of the repo
+	//   type: string
+	//   required: true
+	// - name: repo
+	//   in: path
+	//   description: name of the repo
+	//   type: string
+	//   required: true
+	// - name: branch
+	//   in: path
+	//   description: branch to get
+	//   type: string
+	//   required: true
+	// responses:
+	//   "200":
+	//     "$ref": "#/responses/Branch"
 	if ctx.Repo.TreePath != "" {
 		// if TreePath != "", then URL contained extra slashes
 		// (i.e. "master/subbranch" instead of "master"), so branch does
@@ -42,8 +65,26 @@ func GetBranch(ctx *context.APIContext) {
 }
 
 // ListBranches list all the branches of a repository
-// see https://github.com/gogits/go-gogs-client/wiki/Repositories#list-branches
 func ListBranches(ctx *context.APIContext) {
+	// swagger:operation GET /repos/{owner}/{repo}/branches repository repoListBranches
+	// ---
+	// summary: List a repository's branches
+	// produces:
+	// - application/json
+	// parameters:
+	// - name: owner
+	//   in: path
+	//   description: owner of the repo
+	//   type: string
+	//   required: true
+	// - name: repo
+	//   in: path
+	//   description: name of the repo
+	//   type: string
+	//   required: true
+	// responses:
+	//   "200":
+	//     "$ref": "#/responses/BranchList"
 	branches, err := ctx.Repo.Repository.GetBranches()
 	if err != nil {
 		ctx.Error(500, "GetBranches", err)
diff --git a/routers/api/v1/repo/collaborators.go b/routers/api/v1/repo/collaborators.go
index 31cb9c6b21..f35de08e50 100644
--- a/routers/api/v1/repo/collaborators.go
+++ b/routers/api/v1/repo/collaborators.go
@@ -13,6 +13,25 @@ import (
 
 // ListCollaborators list a repository's collaborators
 func ListCollaborators(ctx *context.APIContext) {
+	// swagger:operation GET /repos/{owner}/{repo}/collaborators repository repoListCollaborators
+	// ---
+	// summary: List a repository's collaborators
+	// produces:
+	// - application/json
+	// parameters:
+	// - name: owner
+	//   in: path
+	//   description: owner of the repo
+	//   type: string
+	//   required: true
+	// - name: repo
+	//   in: path
+	//   description: name of the repo
+	//   type: string
+	//   required: true
+	// responses:
+	//   "200":
+	//     "$ref": "#/responses/UserList"
 	if !ctx.Repo.IsWriter() {
 		ctx.Error(403, "", "User does not have push access")
 		return
@@ -31,6 +50,32 @@ func ListCollaborators(ctx *context.APIContext) {
 
 // IsCollaborator check if a user is a collaborator of a repository
 func IsCollaborator(ctx *context.APIContext) {
+	// swagger:operation GET /repos/{owner}/{repo}/collaborators/{collaborator} repository repoCheckCollaborator
+	// ---
+	// summary: Check if a user is a collaborator of a repository
+	// produces:
+	// - application/json
+	// parameters:
+	// - name: owner
+	//   in: path
+	//   description: owner of the repo
+	//   type: string
+	//   required: true
+	// - name: repo
+	//   in: path
+	//   description: name of the repo
+	//   type: string
+	//   required: true
+	// - name: collaborator
+	//   in: path
+	//   description: username of the collaborator
+	//   type: string
+	//   required: true
+	// responses:
+	//   "204":
+	//     "$ref": "#/responses/empty"
+	//   "404":
+	//     "$ref": "#/responses/empty"
 	if !ctx.Repo.IsWriter() {
 		ctx.Error(403, "", "User does not have push access")
 		return
@@ -56,8 +101,36 @@ func IsCollaborator(ctx *context.APIContext) {
 	}
 }
 
-// AddCollaborator add a collaborator of a repository
+// AddCollaborator add a collaborator to a repository
 func AddCollaborator(ctx *context.APIContext, form api.AddCollaboratorOption) {
+	// swagger:operation PUT /repos/{owner}/{repo}/collaborators/{collaborator} repository repoAddCollaborator
+	// ---
+	// summary: Add a collaborator to a repository
+	// produces:
+	// - application/json
+	// parameters:
+	// - name: owner
+	//   in: path
+	//   description: owner of the repo
+	//   type: string
+	//   required: true
+	// - name: repo
+	//   in: path
+	//   description: name of the repo
+	//   type: string
+	//   required: true
+	// - name: collaborator
+	//   in: path
+	//   description: username of the collaborator to add
+	//   type: string
+	//   required: true
+	// - name: body
+	//   in: body
+	//   schema:
+	//     "$ref": "#/definitions/AddCollaboratorOption"
+	// responses:
+	//   "204":
+	//     "$ref": "#/responses/empty"
 	if !ctx.Repo.IsWriter() {
 		ctx.Error(403, "", "User does not have push access")
 		return
@@ -89,6 +162,30 @@ func AddCollaborator(ctx *context.APIContext, form api.AddCollaboratorOption) {
 
 // DeleteCollaborator delete a collaborator from a repository
 func DeleteCollaborator(ctx *context.APIContext) {
+	// swagger:operation DELETE /repos/{owner}/{repo}/collaborators/{collaborator} repository repoDeleteCollaborator
+	// ---
+	// summary: Delete a collaborator from a repository
+	// produces:
+	// - application/json
+	// parameters:
+	// - name: owner
+	//   in: path
+	//   description: owner of the repo
+	//   type: string
+	//   required: true
+	// - name: repo
+	//   in: path
+	//   description: name of the repo
+	//   type: string
+	//   required: true
+	// - name: collaborator
+	//   in: path
+	//   description: username of the collaborator to delete
+	//   type: string
+	//   required: true
+	// responses:
+	//   "204":
+	//     "$ref": "#/responses/empty"
 	if !ctx.Repo.IsWriter() {
 		ctx.Error(403, "", "User does not have push access")
 		return
diff --git a/routers/api/v1/repo/file.go b/routers/api/v1/repo/file.go
index 9d12a6e136..4ea81255af 100644
--- a/routers/api/v1/repo/file.go
+++ b/routers/api/v1/repo/file.go
@@ -13,8 +13,30 @@ import (
 )
 
 // GetRawFile get a file by path on a repository
-// see https://github.com/gogits/go-gogs-client/wiki/Repositories-Contents#download-raw-content
 func GetRawFile(ctx *context.APIContext) {
+	// swagger:operation GET /repos/{owner}/{repo}/raw/{filepath} repository repoGetRawFile
+	// ---
+	// summary: Get a file from a repository
+	// produces:
+	// - application/json
+	// parameters:
+	// - name: owner
+	//   in: path
+	//   description: owner of the repo
+	//   type: string
+	//   required: true
+	// - name: repo
+	//   in: path
+	//   description: name of the repo
+	//   type: string
+	//   required: true
+	// - name: filepath
+	//   in: path
+	//   description: filepath of the file to get
+	//   type: string
+	//   required: true
+	// responses:
+	//       200:
 	if !ctx.Repo.HasAccess() {
 		ctx.Status(404)
 		return
@@ -40,8 +62,30 @@ func GetRawFile(ctx *context.APIContext) {
 }
 
 // GetArchive get archive of a repository
-// see https://github.com/gogits/go-gogs-client/wiki/Repositories-Contents#download-archive
 func GetArchive(ctx *context.APIContext) {
+	// swagger:operation GET /repos/{owner}/{repo}/archive/{filepath} repository repoGetArchive
+	// ---
+	// summary: Get an archive of a repository
+	// produces:
+	// - application/json
+	// parameters:
+	// - name: owner
+	//   in: path
+	//   description: owner of the repo
+	//   type: string
+	//   required: true
+	// - name: repo
+	//   in: path
+	//   description: name of the repo
+	//   type: string
+	//   required: true
+	// - name: archive
+	//   in: path
+	//   description: archive to download, consisting of a git reference and archive
+	//   type: string
+	//   required: true
+	// responses:
+	//       200:
 	repoPath := models.RepoPath(ctx.Params(":username"), ctx.Params(":reponame"))
 	gitRepo, err := git.OpenRepository(repoPath)
 	if err != nil {
@@ -55,6 +99,29 @@ func GetArchive(ctx *context.APIContext) {
 
 // GetEditorconfig get editor config of a repository
 func GetEditorconfig(ctx *context.APIContext) {
+	// swagger:operation GET /repos/{owner}/{repo}/editorconfig/{filepath} repository repoGetEditorConfig
+	// ---
+	// summary: Get the EditorConfig definitions of a file in a repository
+	// produces:
+	// - application/json
+	// parameters:
+	// - name: owner
+	//   in: path
+	//   description: owner of the repo
+	//   type: string
+	//   required: true
+	// - name: repo
+	//   in: path
+	//   description: name of the repo
+	//   type: string
+	//   required: true
+	// - name: filepath
+	//   in: path
+	//   description: filepath of file to get
+	//   type: string
+	//   required: true
+	// responses:
+	//       200:
 	ec, err := ctx.Repo.GetEditorconfig()
 	if err != nil {
 		if git.IsErrNotExist(err) {
diff --git a/routers/api/v1/repo/fork.go b/routers/api/v1/repo/fork.go
index 2f3addf692..90301cc35e 100644
--- a/routers/api/v1/repo/fork.go
+++ b/routers/api/v1/repo/fork.go
@@ -14,15 +14,25 @@ import (
 
 // ListForks list a repository's forks
 func ListForks(ctx *context.APIContext) {
-	// swagger:route GET /repos/{owner}/{repo}/forks repository listForks
-	//
-	//     Produces:
-	//     - application/json
-	//
-	//     Responses:
-	//       200: RepositoryList
-	//       500: error
-
+	// swagger:operation GET /repos/{owner}/{repo}/forks repository listForks
+	// ---
+	// summary: List a repository's forks
+	// produces:
+	// - application/json
+	// parameters:
+	// - name: owner
+	//   in: path
+	//   description: owner of the repo
+	//   type: string
+	//   required: true
+	// - name: repo
+	//   in: path
+	//   description: name of the repo
+	//   type: string
+	//   required: true
+	// responses:
+	//   "200":
+	//     "$ref": "#/responses/RepositoryList"
 	forks, err := ctx.Repo.Repository.GetForks()
 	if err != nil {
 		ctx.Error(500, "GetForks", err)
@@ -42,17 +52,29 @@ func ListForks(ctx *context.APIContext) {
 
 // CreateFork create a fork of a repo
 func CreateFork(ctx *context.APIContext, form api.CreateForkOption) {
-	// swagger:route POST /repos/{owner}/{repo}/forks repository createFork
-	//
-	//     Produces:
-	//     - application/json
-	//
-	//     Responses:
-	//       202: Repository
-	//       403: forbidden
-	//       422: validationError
-	//       500: error
-
+	// swagger:operation POST /repos/{owner}/{repo}/forks repository createFork
+	// ---
+	// summary: Fork a repository
+	// produces:
+	// - application/json
+	// parameters:
+	// - name: owner
+	//   in: path
+	//   description: owner of the repo to fork
+	//   type: string
+	//   required: true
+	// - name: repo
+	//   in: path
+	//   description: name of the repo to fork
+	//   type: string
+	//   required: true
+	// - name: body
+	//   in: body
+	//   schema:
+	//     "$ref": "#/definitions/CreateForkOption"
+	// responses:
+	//   "202":
+	//     "$ref": "#/responses/Repository"
 	repo := ctx.Repo.Repository
 	var forker *models.User // user/org that will own the fork
 	if form.Organization == nil {
diff --git a/routers/api/v1/repo/hook.go b/routers/api/v1/repo/hook.go
index 72dfeff3d0..2464cc7bd7 100644
--- a/routers/api/v1/repo/hook.go
+++ b/routers/api/v1/repo/hook.go
@@ -15,15 +15,25 @@ import (
 
 // ListHooks list all hooks of a repository
 func ListHooks(ctx *context.APIContext) {
-	// swagger:route GET /repos/{username}/{reponame}/hooks repository repoListHooks
-	//
-	//     Produces:
-	//     - application/json
-	//
-	//     Responses:
-	//       200: HookList
-	//       500: error
-
+	// swagger:operation GET /repos/{owner}/{repo}/hooks repository repoListHooks
+	// ---
+	// summary: List the hooks in a repository
+	// produces:
+	// - application/json
+	// parameters:
+	// - name: owner
+	//   in: path
+	//   description: owner of the repo
+	//   type: string
+	//   required: true
+	// - name: repo
+	//   in: path
+	//   description: name of the repo
+	//   type: string
+	//   required: true
+	// responses:
+	//   "200":
+	//     "$ref": "#/responses/HookList"
 	hooks, err := models.GetWebhooksByRepoID(ctx.Repo.Repository.ID)
 	if err != nil {
 		ctx.Error(500, "GetWebhooksByRepoID", err)
@@ -39,6 +49,30 @@ func ListHooks(ctx *context.APIContext) {
 
 // GetHook get a repo's hook by id
 func GetHook(ctx *context.APIContext) {
+	// swagger:operation GET /repos/{owner}/{repo}/hooks/{id} repository repoGetHook
+	// ---
+	// summary: Get a hook
+	// produces:
+	// - application/json
+	// parameters:
+	// - name: owner
+	//   in: path
+	//   description: owner of the repo
+	//   type: string
+	//   required: true
+	// - name: repo
+	//   in: path
+	//   description: name of the repo
+	//   type: string
+	//   required: true
+	// - name: id
+	//   in: path
+	//   description: id of the hook to get
+	//   type: integer
+	//   required: true
+	// responses:
+	//   "200":
+	//     "$ref": "#/responses/Hook"
 	repo := ctx.Repo
 	hookID := ctx.ParamsInt64(":id")
 	hook, err := utils.GetRepoHook(ctx, repo.Repository.ID, hookID)
@@ -50,19 +84,31 @@ func GetHook(ctx *context.APIContext) {
 
 // CreateHook create a hook for a repository
 func CreateHook(ctx *context.APIContext, form api.CreateHookOption) {
-	// swagger:route POST /repos/{username}/{reponame}/hooks repository repoCreateHook
-	//
-	//     Consumes:
-	//     - application/json
-	//
-	//     Produces:
-	//     - application/json
-	//
-	//     Responses:
-	//       200: Hook
-	//       422: validationError
-	//       500: error
-
+	// swagger:operation POST /repos/{owner}/{repo}/hooks repository repoCreateHook
+	// ---
+	// summary: Create a hook
+	// consumes:
+	// - application/json
+	// produces:
+	// - application/json
+	// parameters:
+	// - name: owner
+	//   in: path
+	//   description: owner of the repo
+	//   type: string
+	//   required: true
+	// - name: repo
+	//   in: path
+	//   description: name of the repo
+	//   type: string
+	//   required: true
+	// - name: body
+	//   in: body
+	//   schema:
+	//     "$ref": "#/definitions/CreateHookOption"
+	// responses:
+	//   "200":
+	//     "$ref": "#/responses/Hook"
 	if !utils.CheckCreateHookOption(ctx, &form) {
 		return
 	}
@@ -71,32 +117,61 @@ func CreateHook(ctx *context.APIContext, form api.CreateHookOption) {
 
 // EditHook modify a hook of a repository
 func EditHook(ctx *context.APIContext, form api.EditHookOption) {
-	// swagger:route PATCH /repos/{username}/{reponame}/hooks/{id} repository repoEditHook
-	//
-	//     Produces:
-	//     - application/json
-	//
-	//     Responses:
-	//       200: Hook
-	//       422: validationError
-	//       500: error
-
+	// swagger:operation PATCH /repos/{owner}/{repo}/hooks/{id} repository repoEditHook
+	// ---
+	// summary: Edit a hook in a repository
+	// produces:
+	// - application/json
+	// parameters:
+	// - name: owner
+	//   in: path
+	//   description: owner of the repo
+	//   type: string
+	//   required: true
+	// - name: repo
+	//   in: path
+	//   description: name of the repo
+	//   type: string
+	//   required: true
+	// - name: body
+	//   in: body
+	//   schema:
+	//     "$ref": "#/definitions/EditHookOption"
+	// responses:
+	//   "200":
+	//     "$ref": "#/responses/Hook"
 	hookID := ctx.ParamsInt64(":id")
 	utils.EditRepoHook(ctx, &form, hookID)
 }
 
 // DeleteHook delete a hook of a repository
 func DeleteHook(ctx *context.APIContext) {
-	// swagger:route DELETE /repos/{username}/{reponame}/hooks/{id} repository repoDeleteHook
-	//
-	//     Produces:
-	//     - application/json
-	//
-	//     Responses:
-	//       204: empty
-	//       404: notFound
-	//       500: error
-
+	// swagger:operation DELETE /repos/{user}/{repo}/hooks/{id} repository repoDeleteHook
+	// ---
+	// summary: Delete a hook in a repository
+	// produces:
+	// - application/json
+	// parameters:
+	// - name: owner
+	//   in: path
+	//   description: owner of the repo
+	//   type: string
+	//   required: true
+	// - name: repo
+	//   in: path
+	//   description: name of the repo
+	//   type: string
+	//   required: true
+	// - name: id
+	//   in: path
+	//   description: id of the hook to delete
+	//   type: integer
+	//   required: true
+	// responses:
+	//   "204":
+	//     "$ref": "#/responses/empty"
+	//   "404":
+	//     "$ref": "#/responses/notFound"
 	if err := models.DeleteWebhookByRepoID(ctx.Repo.Repository.ID, ctx.ParamsInt64(":id")); err != nil {
 		if models.IsErrWebhookNotExist(err) {
 			ctx.Status(404)
diff --git a/routers/api/v1/repo/issue.go b/routers/api/v1/repo/issue.go
index 2debe67c3b..08815ee074 100644
--- a/routers/api/v1/repo/issue.go
+++ b/routers/api/v1/repo/issue.go
@@ -18,6 +18,33 @@ import (
 
 // ListIssues list the issues of a repository
 func ListIssues(ctx *context.APIContext) {
+	// swagger:operation GET /repos/{owner}/{repo}/issues issue issueListIssues
+	// ---
+	// summary: List a repository's issues
+	// produces:
+	// - application/json
+	// parameters:
+	// - name: owner
+	//   in: path
+	//   description: owner of the repo
+	//   type: string
+	//   required: true
+	// - name: repo
+	//   in: path
+	//   description: name of the repo
+	//   type: string
+	//   required: true
+	// - name: state
+	//   in: query
+	//   description: whether issue is open or closed
+	//   type: string
+	// - name: page
+	//   in: query
+	//   description: page number of requested issues
+	//   type: integer
+	// responses:
+	//   "200":
+	//     "$ref": "#/responses/IssueList"
 	var isClosed util.OptionalBool
 	switch ctx.Query("state") {
 	case "closed":
@@ -50,6 +77,30 @@ func ListIssues(ctx *context.APIContext) {
 
 // GetIssue get an issue of a repository
 func GetIssue(ctx *context.APIContext) {
+	// swagger:operation GET /repos/{owner}/{repo}/issues/{id} issue issueGetIssue
+	// ---
+	// summary: Get an issue by id
+	// produces:
+	// - application/json
+	// parameters:
+	// - name: owner
+	//   in: path
+	//   description: owner of the repo
+	//   type: string
+	//   required: true
+	// - name: repo
+	//   in: path
+	//   description: name of the repo
+	//   type: string
+	//   required: true
+	// - name: id
+	//   in: path
+	//   description: id of the issue to get
+	//   type: integer
+	//   required: true
+	// responses:
+	//   "200":
+	//     "$ref": "#/responses/Issue"
 	issue, err := models.GetIssueByIndex(ctx.Repo.Repository.ID, ctx.ParamsInt64(":index"))
 	if err != nil {
 		if models.IsErrIssueNotExist(err) {
@@ -64,6 +115,31 @@ func GetIssue(ctx *context.APIContext) {
 
 // CreateIssue create an issue of a repository
 func CreateIssue(ctx *context.APIContext, form api.CreateIssueOption) {
+	// swagger:operation POST /repos/{owner}/{repo}/issues issue issueCreateIssue
+	// ---
+	// summary: Create an issue
+	// consumes:
+	// - application/json
+	// produces:
+	// - application/json
+	// parameters:
+	// - name: owner
+	//   in: path
+	//   description: owner of the repo
+	//   type: string
+	//   required: true
+	// - name: repo
+	//   in: path
+	//   description: name of the repo
+	//   type: string
+	//   required: true
+	// - name: body
+	//   in: body
+	//   schema:
+	//     "$ref": "#/definitions/CreateIssueOption"
+	// responses:
+	//   "201":
+	//     "$ref": "#/responses/Issue"
 	issue := &models.Issue{
 		RepoID:   ctx.Repo.Repository.ID,
 		Title:    form.Title,
@@ -114,6 +190,36 @@ func CreateIssue(ctx *context.APIContext, form api.CreateIssueOption) {
 
 // EditIssue modify an issue of a repository
 func EditIssue(ctx *context.APIContext, form api.EditIssueOption) {
+	// swagger:operation PATCH /repos/{owner}/{repo}/issues/{id} issue issueEditIssue
+	// ---
+	// summary: Edit an issue
+	// consumes:
+	// - application/json
+	// produces:
+	// - application/json
+	// parameters:
+	// - name: owner
+	//   in: path
+	//   description: owner of the repo
+	//   type: string
+	//   required: true
+	// - name: repo
+	//   in: path
+	//   description: name of the repo
+	//   type: string
+	//   required: true
+	// - name: id
+	//   in: path
+	//   description: id of the issue to edit
+	//   type: integer
+	//   required: true
+	// - name: body
+	//   in: body
+	//   schema:
+	//     "$ref": "#/definitions/EditIssueOption"
+	// responses:
+	//   "201":
+	//     "$ref": "#/responses/Issue"
 	issue, err := models.GetIssueByIndex(ctx.Repo.Repository.ID, ctx.ParamsInt64(":index"))
 	if err != nil {
 		if models.IsErrIssueNotExist(err) {
diff --git a/routers/api/v1/repo/issue_comment.go b/routers/api/v1/repo/issue_comment.go
index b57511a2de..f0b0353d1b 100644
--- a/routers/api/v1/repo/issue_comment.go
+++ b/routers/api/v1/repo/issue_comment.go
@@ -15,6 +15,34 @@ import (
 
 // ListIssueComments list all the comments of an issue
 func ListIssueComments(ctx *context.APIContext) {
+	// swagger:operation GET /repos/{owner}/{repo}/issue/{index}/comments issue issueGetComments
+	// ---
+	// summary: List all comments on an issue
+	// produces:
+	// - application/json
+	// parameters:
+	// - name: owner
+	//   in: path
+	//   description: owner of the repo
+	//   type: string
+	//   required: true
+	// - name: repo
+	//   in: path
+	//   description: name of the repo
+	//   type: string
+	//   required: true
+	// - name: id
+	//   in: path
+	//   description: index of the issue
+	//   type: integer
+	//   required: true
+	// - name: string
+	//   in: query
+	//   description: if provided, only comments updated since the specified time are returned.
+	//   type: string
+	// responses:
+	//   "200":
+	//     "$ref": "#/responses/CommentList"
 	var since time.Time
 	if len(ctx.Query("since")) > 0 {
 		since, _ = time.Parse(time.RFC3339, ctx.Query("since"))
@@ -44,8 +72,31 @@ func ListIssueComments(ctx *context.APIContext) {
 	ctx.JSON(200, &apiComments)
 }
 
-// ListRepoIssueComments returns all issue-comments for an issue
+// ListRepoIssueComments returns all issue-comments for a repo
 func ListRepoIssueComments(ctx *context.APIContext) {
+	// swagger:operation GET /repos/{owner}/{repo}/issues/comments issue issueGetRepoComments
+	// ---
+	// summary: List all comments in a repository
+	// produces:
+	// - application/json
+	// parameters:
+	// - name: owner
+	//   in: path
+	//   description: owner of the repo
+	//   type: string
+	//   required: true
+	// - name: repo
+	//   in: path
+	//   description: name of the repo
+	//   type: string
+	//   required: true
+	// - name: string
+	//   in: query
+	//   description: if provided, only comments updated since the provided time are returned.
+	//   type: string
+	// responses:
+	//   "200":
+	//     "$ref": "#/responses/CommentList"
 	var since time.Time
 	if len(ctx.Query("since")) > 0 {
 		since, _ = time.Parse(time.RFC3339, ctx.Query("since"))
@@ -70,6 +121,36 @@ func ListRepoIssueComments(ctx *context.APIContext) {
 
 // CreateIssueComment create a comment for an issue
 func CreateIssueComment(ctx *context.APIContext, form api.CreateIssueCommentOption) {
+	// swagger:operation POST /repos/{owner}/{repo}/issues/{index}/comments issue issueCreateComment
+	// ---
+	// summary: Add a comment to an issue
+	// consumes:
+	// - application/json
+	// produces:
+	// - application/json
+	// parameters:
+	// - name: owner
+	//   in: path
+	//   description: owner of the repo
+	//   type: string
+	//   required: true
+	// - name: repo
+	//   in: path
+	//   description: name of the repo
+	//   type: string
+	//   required: true
+	// - name: id
+	//   in: path
+	//   description: index of the issue
+	//   type: integer
+	//   required: true
+	// - name: body
+	//   in: body
+	//   schema:
+	//     "$ref": "#/definitions/CreateIssueOption"
+	// responses:
+	//   "201":
+	//     "$ref": "#/responses/Comment"
 	issue, err := models.GetIssueByIndex(ctx.Repo.Repository.ID, ctx.ParamsInt64(":index"))
 	if err != nil {
 		ctx.Error(500, "GetIssueByIndex", err)
@@ -87,6 +168,36 @@ func CreateIssueComment(ctx *context.APIContext, form api.CreateIssueCommentOpti
 
 // EditIssueComment modify a comment of an issue
 func EditIssueComment(ctx *context.APIContext, form api.EditIssueCommentOption) {
+	// swagger:operation PATCH /repos/{owner}/{repo}/comments/{id} issue issueEditComment
+	// ---
+	// summary: Edit a comment
+	// consumes:
+	// - application/json
+	// produces:
+	// - application/json
+	// parameters:
+	// - name: owner
+	//   in: path
+	//   description: owner of the repo
+	//   type: string
+	//   required: true
+	// - name: repo
+	//   in: path
+	//   description: name of the repo
+	//   type: string
+	//   required: true
+	// - name: id
+	//   in: path
+	//   description: id of the comment to edit
+	//   type: integer
+	//   required: true
+	// - name: body
+	//   in: body
+	//   schema:
+	//     "$ref": "#/definitions/EditIssueCommentOption"
+	// responses:
+	//   "200":
+	//     "$ref": "#/responses/Comment"
 	comment, err := models.GetCommentByID(ctx.ParamsInt64(":id"))
 	if err != nil {
 		if models.IsErrCommentNotExist(err) {
@@ -115,6 +226,28 @@ func EditIssueComment(ctx *context.APIContext, form api.EditIssueCommentOption)
 
 // DeleteIssueComment delete a comment from an issue
 func DeleteIssueComment(ctx *context.APIContext) {
+	// swagger:operation DELETE /repos/{owner}/{repo}/comments/{id} issue issueDeleteComment
+	// ---
+	// summary: Delete a comment
+	// parameters:
+	// - name: owner
+	//   in: path
+	//   description: owner of the repo
+	//   type: string
+	//   required: true
+	// - name: repo
+	//   in: path
+	//   description: name of the repo
+	//   type: string
+	//   required: true
+	// - name: id
+	//   in: path
+	//   description: id of comment to delete
+	//   type: integer
+	//   required: true
+	// responses:
+	//   "204":
+	//     "$ref": "#/responses/empty"
 	comment, err := models.GetCommentByID(ctx.ParamsInt64(":id"))
 	if err != nil {
 		if models.IsErrCommentNotExist(err) {
diff --git a/routers/api/v1/repo/issue_label.go b/routers/api/v1/repo/issue_label.go
index 2eec743e70..fde919e506 100644
--- a/routers/api/v1/repo/issue_label.go
+++ b/routers/api/v1/repo/issue_label.go
@@ -13,6 +13,32 @@ import (
 
 // ListIssueLabels list all the labels of an issue
 func ListIssueLabels(ctx *context.APIContext) {
+	// swagger:operation GET /repos/{owner}/{repo}/issues/{index}/labels issue issueGetLabels
+	// ---
+	// summary: Get an issue's labels
+	// produces:
+	// - application/json
+	// parameters:
+	// - name: owner
+	//   in: path
+	//   description: owner of the repo
+	//   type: string
+	//   required: true
+	// - name: repo
+	//   in: path
+	//   description: name of the repo
+	//   type: string
+	//   required: true
+	// - name: index
+	//   in: path
+	//   description: index of the issue
+	//   type: integer
+	//   required: true
+	// responses:
+	//   "200":
+	//     "$ref": "#/responses/LabelList"
+	//   "404":
+	//     "$ref": "#/responses/notFound"
 	issue, err := models.GetIssueByIndex(ctx.Repo.Repository.ID, ctx.ParamsInt64(":index"))
 	if err != nil {
 		if models.IsErrIssueNotExist(err) {
@@ -32,6 +58,36 @@ func ListIssueLabels(ctx *context.APIContext) {
 
 // AddIssueLabels add labels for an issue
 func AddIssueLabels(ctx *context.APIContext, form api.IssueLabelsOption) {
+	// swagger:operation POST /repos/{owner}/{repo}/issue/{index}/labels issue issueAddLabel
+	// ---
+	// summary: Add a label to an issue
+	// consumes:
+	// - application/json
+	// produces:
+	// - application/json
+	// parameters:
+	// - name: owner
+	//   in: path
+	//   description: owner of the repo
+	//   type: string
+	//   required: true
+	// - name: repo
+	//   in: path
+	//   description: name of the repo
+	//   type: string
+	//   required: true
+	// - name: index
+	//   in: path
+	//   description: index of the issue
+	//   type: integer
+	//   required: true
+	// - name: body
+	//   in: body
+	//   schema:
+	//     "$ref": "#/definitions/IssueLabelsOption"
+	// responses:
+	//   "200":
+	//     "$ref": "#/responses/LabelList"
 	if !ctx.Repo.IsWriter() {
 		ctx.Status(403)
 		return
@@ -73,6 +129,35 @@ func AddIssueLabels(ctx *context.APIContext, form api.IssueLabelsOption) {
 
 // DeleteIssueLabel delete a label for an issue
 func DeleteIssueLabel(ctx *context.APIContext) {
+	// swagger:operation DELETE /repos/{owner}/{repo}/issue/{index}/labels/{id} issue issueRemoveLabel
+	// ---
+	// summary: Remove a label from an issue
+	// produces:
+	// - application/json
+	// parameters:
+	// - name: owner
+	//   in: path
+	//   description: owner of the repo
+	//   type: string
+	//   required: true
+	// - name: repo
+	//   in: path
+	//   description: name of the repo
+	//   type: string
+	//   required: true
+	// - name: index
+	//   in: path
+	//   description: index of the issue
+	//   type: integer
+	//   required: true
+	// - name: id
+	//   in: path
+	//   description: id of the label to remove
+	//   type: integer
+	//   required: true
+	// responses:
+	//   "204":
+	//     "$ref": "#/responses/empty"
 	if !ctx.Repo.IsWriter() {
 		ctx.Status(403)
 		return
@@ -108,6 +193,36 @@ func DeleteIssueLabel(ctx *context.APIContext) {
 
 // ReplaceIssueLabels replace labels for an issue
 func ReplaceIssueLabels(ctx *context.APIContext, form api.IssueLabelsOption) {
+	// swagger:operation PUT /repos/{owner}/{repo}/issue/{index}/labels issue issueReplaceLabels
+	// ---
+	// summary: Replace an issue's labels
+	// consumes:
+	// - application/json
+	// produces:
+	// - application/json
+	// parameters:
+	// - name: owner
+	//   in: path
+	//   description: owner of the repo
+	//   type: string
+	//   required: true
+	// - name: repo
+	//   in: path
+	//   description: name of the repo
+	//   type: string
+	//   required: true
+	// - name: index
+	//   in: path
+	//   description: index of the issue
+	//   type: integer
+	//   required: true
+	// - name: body
+	//   in: body
+	//   schema:
+	//     "$ref": "#/definitions/IssueLabelsOption"
+	// responses:
+	//   "200":
+	//     "$ref": "#/responses/LabelList"
 	if !ctx.Repo.IsWriter() {
 		ctx.Status(403)
 		return
@@ -149,6 +264,30 @@ func ReplaceIssueLabels(ctx *context.APIContext, form api.IssueLabelsOption) {
 
 // ClearIssueLabels delete all the labels for an issue
 func ClearIssueLabels(ctx *context.APIContext) {
+	// swagger:operation DELETE /repos/{owner}/{repo}/issue/{index}/labels issue issueClearLabels
+	// ---
+	// summary: Remove all labels from an issue
+	// produces:
+	// - application/json
+	// parameters:
+	// - name: owner
+	//   in: path
+	//   description: owner of the repo
+	//   type: string
+	//   required: true
+	// - name: repo
+	//   in: path
+	//   description: name of the repo
+	//   type: string
+	//   required: true
+	// - name: index
+	//   in: path
+	//   description: index of the issue
+	//   type: integer
+	//   required: true
+	// responses:
+	//   "204":
+	//     "$ref": "#/responses/empty"
 	if !ctx.Repo.IsWriter() {
 		ctx.Status(403)
 		return
diff --git a/routers/api/v1/repo/issue_tracked_time.go b/routers/api/v1/repo/issue_tracked_time.go
index 3962a7b0e2..15d898d5d5 100644
--- a/routers/api/v1/repo/issue_tracked_time.go
+++ b/routers/api/v1/repo/issue_tracked_time.go
@@ -20,15 +20,30 @@ func trackedTimesToAPIFormat(trackedTimes []*models.TrackedTime) []*api.TrackedT
 
 // ListTrackedTimes list all the tracked times of an issue
 func ListTrackedTimes(ctx *context.APIContext) {
-	// swagger:route GET /repos/{username}/{reponame}/issues/{issue}/times repository issueTrackedTimes
-	//
-	//     Produces:
-	//     - application/json
-	//
-	//     Responses:
-	//       200: TrackedTimes
-	//	 404: error
-	//       500: error
+	// swagger:operation GET /repos/{owner}/{repo}/issues/{index}/times issue issueTrackedTimes
+	// ---
+	// summary: List an issue's tracked times
+	// produces:
+	// - application/json
+	// parameters:
+	// - name: owner
+	//   in: path
+	//   description: owner of the repo
+	//   type: string
+	//   required: true
+	// - name: repo
+	//   in: path
+	//   description: name of the repo
+	//   type: string
+	//   required: true
+	// - name: repo
+	//   in: path
+	//   description: index of the issue
+	//   type: integer
+	//   required: true
+	// responses:
+	//   "200":
+	//     "$ref": "#/responses/TrackedTimeList"
 	if !ctx.Repo.Repository.IsTimetrackerEnabled() {
 		ctx.Error(404, "IsTimetrackerEnabled", "Timetracker is diabled")
 		return
@@ -54,17 +69,40 @@ func ListTrackedTimes(ctx *context.APIContext) {
 
 // AddTime adds time manual to the given issue
 func AddTime(ctx *context.APIContext, form api.AddTimeOption) {
-	// swagger:route Post /repos/{username}/{reponame}/issues/{issue}/times repository addTime
-	//
-	//     Produces:
-	//     - application/json
-	//
-	//     Responses:
-	//       200: TrackedTime
-	//       400: error
-	//       403: error
-	//	 404: error
-	//       500: error
+	// swagger:operation Post /repos/{owner}/{repo}/issues/{index}/times issue issueAddTime
+	// ---
+	// summary: Add a tracked time to a issue
+	// consumes:
+	// - application/json
+	// produces:
+	// - application/json
+	// parameters:
+	// - name: owner
+	//   in: path
+	//   description: owner of the repo
+	//   type: string
+	//   required: true
+	// - name: repo
+	//   in: path
+	//   description: name of the repo
+	//   type: string
+	//   required: true
+	// - name: id
+	//   in: path
+	//   description: index of the issue to add tracked time to
+	//   type: integer
+	//   required: true
+	// - name: body
+	//   in: body
+	//   schema:
+	//     "$ref": "#/definitions/AddTimeOption"
+	// responses:
+	//   "200":
+	//     "$ref": "#/responses/TrackedTime"
+	//   "400":
+	//     "$ref": "#/responses/error"
+	//   "403":
+	//     "$ref": "#/responses/error"
 	issue, err := models.GetIssueByIndex(ctx.Repo.Repository.ID, ctx.ParamsInt64(":index"))
 	if err != nil {
 		if models.IsErrIssueNotExist(err) {
@@ -93,16 +131,30 @@ func AddTime(ctx *context.APIContext, form api.AddTimeOption) {
 
 // ListTrackedTimesByUser  lists all tracked times of the user
 func ListTrackedTimesByUser(ctx *context.APIContext) {
-	// swagger:route GET /repos/{username}/{reponame}/times/{timetrackingusername} user userTrackedTimes
-	//
-	//     Produces:
-	//     - application/json
-	//
-	//     Responses:
-	//       200: TrackedTimes
-	//       400: error
-	//	 404: error
-	//       500: error
+	// swagger:operation GET /repos/{owner}/{repo}/times/{tracker} user userTrackedTimes
+	// ---
+	// summary: List a user's tracked times in a repo
+	// produces:
+	// - application/json
+	// parameters:
+	// - name: owner
+	//   in: path
+	//   description: owner of the repo
+	//   type: string
+	//   required: true
+	// - name: repo
+	//   in: path
+	//   description: name of the repo
+	//   type: string
+	//   required: true
+	// - name: user
+	//   in: path
+	//   description: username of user
+	//   type: string
+	//   required: true
+	// responses:
+	//   "200":
+	//     "$ref": "#/responses/TrackedTimeList"
 	if !ctx.Repo.Repository.IsTimetrackerEnabled() {
 		ctx.JSON(400, struct{ Message string }{Message: "time tracking disabled"})
 		return
@@ -131,17 +183,27 @@ func ListTrackedTimesByUser(ctx *context.APIContext) {
 	ctx.JSON(200, &apiTrackedTimes)
 }
 
-// ListTrackedTimesByRepository lists all tracked times of the user
+// ListTrackedTimesByRepository lists all tracked times of the repository
 func ListTrackedTimesByRepository(ctx *context.APIContext) {
-	// swagger:route GET /repos/{username}/{reponame}/times repository repoTrackedTimes
-	//
-	//     Produces:
-	//     - application/json
-	//
-	//     Responses:
-	//       200: TrackedTimes
-	//       400: error
-	//       500: error
+	// swagger:operation GET /repos/{owner}/{repo}/times repository repoTrackedTimes
+	// ---
+	// summary: List a repo's tracked times
+	// produces:
+	// - application/json
+	// parameters:
+	// - name: owner
+	//   in: path
+	//   description: owner of the repo
+	//   type: string
+	//   required: true
+	// - name: repo
+	//   in: path
+	//   description: name of the repo
+	//   type: string
+	//   required: true
+	// responses:
+	//   "200":
+	//     "$ref": "#/responses/TrackedTimeList"
 	if !ctx.Repo.Repository.IsTimetrackerEnabled() {
 		ctx.JSON(400, struct{ Message string }{Message: "time tracking disabled"})
 		return
@@ -158,14 +220,14 @@ func ListTrackedTimesByRepository(ctx *context.APIContext) {
 
 // ListMyTrackedTimes lists all tracked times of the current user
 func ListMyTrackedTimes(ctx *context.APIContext) {
-	// swagger:route GET /user/times user userTrackedTimes
-	//
-	//     Produces:
-	//     - application/json
-	//
-	//     Responses:
-	//       200: TrackedTimes
-	//       500: error
+	// swagger:operation GET /user/times user userCurrentTrackedTimes
+	// ---
+	// summary: List the current user's tracked times
+	// produces:
+	// - application/json
+	// responses:
+	//   "200":
+	//     "$ref": "#/responses/TrackedTimeList"
 	trackedTimes, err := models.GetTrackedTimes(models.FindTrackedTimesOptions{UserID: ctx.User.ID})
 	if err != nil {
 		ctx.Error(500, "GetTrackedTimesByUser", err)
diff --git a/routers/api/v1/repo/key.go b/routers/api/v1/repo/key.go
index 546cc40e61..a20f4c829e 100644
--- a/routers/api/v1/repo/key.go
+++ b/routers/api/v1/repo/key.go
@@ -20,8 +20,26 @@ func composeDeployKeysAPILink(repoPath string) string {
 }
 
 // ListDeployKeys list all the deploy keys of a repository
-// see https://github.com/gogits/go-gogs-client/wiki/Repositories-Deploy-Keys#list-deploy-keys
 func ListDeployKeys(ctx *context.APIContext) {
+	// swagger:operation GET /repos/{owner}/{repo}/keys repository repoListKeys
+	// ---
+	// summary: List a repository's keys
+	// produces:
+	// - application/json
+	// parameters:
+	// - name: owner
+	//   in: path
+	//   description: owner of the repo
+	//   type: string
+	//   required: true
+	// - name: repo
+	//   in: path
+	//   description: name of the repo
+	//   type: string
+	//   required: true
+	// responses:
+	//   "200":
+	//     "$ref": "#/responses/DeployKeyList"
 	keys, err := models.ListDeployKeys(ctx.Repo.Repository.ID)
 	if err != nil {
 		ctx.Error(500, "ListDeployKeys", err)
@@ -42,8 +60,31 @@ func ListDeployKeys(ctx *context.APIContext) {
 }
 
 // GetDeployKey get a deploy key by id
-// see https://github.com/gogits/go-gogs-client/wiki/Repositories-Deploy-Keys#get-a-deploy-key
 func GetDeployKey(ctx *context.APIContext) {
+	// swagger:operation GET /repos/{owner}/{repo}/keys/{id} repository repoGetKey
+	// ---
+	// summary: Get a repository's key by id
+	// produces:
+	// - application/json
+	// parameters:
+	// - name: owner
+	//   in: path
+	//   description: owner of the repo
+	//   type: string
+	//   required: true
+	// - name: repo
+	//   in: path
+	//   description: name of the repo
+	//   type: string
+	//   required: true
+	// - name: id
+	//   in: path
+	//   description: id of the key to get
+	//   type: integer
+	//   required: true
+	// responses:
+	//   "200":
+	//     "$ref": "#/responses/DeployKey"
 	key, err := models.GetDeployKeyByID(ctx.ParamsInt64(":id"))
 	if err != nil {
 		if models.IsErrDeployKeyNotExist(err) {
@@ -85,8 +126,32 @@ func HandleAddKeyError(ctx *context.APIContext, err error) {
 }
 
 // CreateDeployKey create deploy key for a repository
-// see https://github.com/gogits/go-gogs-client/wiki/Repositories-Deploy-Keys#add-a-new-deploy-key
 func CreateDeployKey(ctx *context.APIContext, form api.CreateKeyOption) {
+	// swagger:operation POST /repos/{owner}/{repo}/keys repository repoCreateKey
+	// ---
+	// summary: Add a key to a repository
+	// consumes:
+	// - application/json
+	// produces:
+	// - application/json
+	// parameters:
+	// - name: owner
+	//   in: path
+	//   description: owner of the repo
+	//   type: string
+	//   required: true
+	// - name: repo
+	//   in: path
+	//   description: name of the repo
+	//   type: string
+	//   required: true
+	// - name: body
+	//   in: body
+	//   schema:
+	//     "$ref": "#/definitions/CreateKeyOption"
+	// responses:
+	//   "201":
+	//     "$ref": "#/responses/DeployKey"
 	content, err := models.CheckPublicKeyString(form.Key)
 	if err != nil {
 		HandleCheckKeyStringError(ctx, err)
@@ -105,8 +170,29 @@ func CreateDeployKey(ctx *context.APIContext, form api.CreateKeyOption) {
 }
 
 // DeleteDeploykey delete deploy key for a repository
-// see https://github.com/gogits/go-gogs-client/wiki/Repositories-Deploy-Keys#remove-a-deploy-key
 func DeleteDeploykey(ctx *context.APIContext) {
+	// swagger:operation DELETE /repos/{owner}/{repo}/keys/{id} repository repoDeleteKey
+	// ---
+	// summary: Delete a key from a repository
+	// parameters:
+	// - name: owner
+	//   in: path
+	//   description: owner of the repo
+	//   type: string
+	//   required: true
+	// - name: repo
+	//   in: path
+	//   description: name of the repo
+	//   type: string
+	//   required: true
+	// - name: id
+	//   in: path
+	//   description: id of the key to delete
+	//   type: integer
+	//   required: true
+	// responses:
+	//   "204":
+	//     "$ref": "#/responses/empty"
 	if err := models.DeleteDeployKey(ctx.User, ctx.ParamsInt64(":id")); err != nil {
 		if models.IsErrKeyAccessDenied(err) {
 			ctx.Error(403, "", "You do not have access to this key")
diff --git a/routers/api/v1/repo/label.go b/routers/api/v1/repo/label.go
index c932fb1585..cb724c7182 100644
--- a/routers/api/v1/repo/label.go
+++ b/routers/api/v1/repo/label.go
@@ -15,6 +15,25 @@ import (
 
 // ListLabels list all the labels of a repository
 func ListLabels(ctx *context.APIContext) {
+	// swagger:operation GET /repos/{owner}/{repo}/labels issue issueListLabels
+	// ---
+	// summary: Get all of a repository's labels
+	// produces:
+	// - application/json
+	// parameters:
+	// - name: owner
+	//   in: path
+	//   description: owner of the repo
+	//   type: string
+	//   required: true
+	// - name: repo
+	//   in: path
+	//   description: name of the repo
+	//   type: string
+	//   required: true
+	// responses:
+	//   "200":
+	//     "$ref": "#/responses/LabelList"
 	labels, err := models.GetLabelsByRepoID(ctx.Repo.Repository.ID, ctx.Query("sort"))
 	if err != nil {
 		ctx.Error(500, "GetLabelsByRepoID", err)
@@ -30,6 +49,30 @@ func ListLabels(ctx *context.APIContext) {
 
 // GetLabel get label by repository and label id
 func GetLabel(ctx *context.APIContext) {
+	// swagger:operation GET /repos/{owner}/{repo}/labels/{id} issue issueGetLabel
+	// ---
+	// summary: Get a single label
+	// produces:
+	// - application/json
+	// parameters:
+	// - name: owner
+	//   in: path
+	//   description: owner of the repo
+	//   type: string
+	//   required: true
+	// - name: repo
+	//   in: path
+	//   description: name of the repo
+	//   type: string
+	//   required: true
+	// - name: id
+	//   in: path
+	//   description: id of the label to get
+	//   type: integer
+	//   required: true
+	// responses:
+	//   "200":
+	//     "$ref": "#/responses/Label"
 	var (
 		label *models.Label
 		err   error
@@ -54,6 +97,31 @@ func GetLabel(ctx *context.APIContext) {
 
 // CreateLabel create a label for a repository
 func CreateLabel(ctx *context.APIContext, form api.CreateLabelOption) {
+	// swagger:operation POST /repos/{owner}/{repo}/labels issue issueCreateLabel
+	// ---
+	// summary: Create a label
+	// consumes:
+	// - application/json
+	// produces:
+	// - application/json
+	// parameters:
+	// - name: owner
+	//   in: path
+	//   description: owner of the repo
+	//   type: string
+	//   required: true
+	// - name: repo
+	//   in: path
+	//   description: name of the repo
+	//   type: string
+	//   required: true
+	// - name: body
+	//   in: body
+	//   schema:
+	//     "$ref": "#/definitions/CreateLabelOption"
+	// responses:
+	//   "201":
+	//     "$ref": "#/responses/Label"
 	if !ctx.Repo.IsWriter() {
 		ctx.Status(403)
 		return
@@ -73,6 +141,36 @@ func CreateLabel(ctx *context.APIContext, form api.CreateLabelOption) {
 
 // EditLabel modify a label for a repository
 func EditLabel(ctx *context.APIContext, form api.EditLabelOption) {
+	// swagger:operation PATCH /repos/{owner}/{repo}/labels/{id} issue issueEditLabel
+	// ---
+	// summary: Update a label
+	// consumes:
+	// - application/json
+	// produces:
+	// - application/json
+	// parameters:
+	// - name: owner
+	//   in: path
+	//   description: owner of the repo
+	//   type: string
+	//   required: true
+	// - name: repo
+	//   in: path
+	//   description: name of the repo
+	//   type: string
+	//   required: true
+	// - name: id
+	//   in: path
+	//   description: id of the label to edit
+	//   type: integer
+	//   required: true
+	// - name: body
+	//   in: body
+	//   schema:
+	//     "$ref": "#/definitions/EditLabelOption"
+	// responses:
+	//   "200":
+	//     "$ref": "#/responses/Label"
 	if !ctx.Repo.IsWriter() {
 		ctx.Status(403)
 		return
@@ -103,6 +201,28 @@ func EditLabel(ctx *context.APIContext, form api.EditLabelOption) {
 
 // DeleteLabel delete a label for a repository
 func DeleteLabel(ctx *context.APIContext) {
+	// swagger:operation DELETE /repos/{owner}/{repo}/labels/{id} issue issueDeleteLabel
+	// ---
+	// summary: Delete a label
+	// parameters:
+	// - name: owner
+	//   in: path
+	//   description: owner of the repo
+	//   type: string
+	//   required: true
+	// - name: repo
+	//   in: path
+	//   description: name of the repo
+	//   type: string
+	//   required: true
+	// - name: id
+	//   in: path
+	//   description: id of the label to delete
+	//   type: integer
+	//   required: true
+	// responses:
+	//   "204":
+	//     "$ref": "#/responses/empty"
 	if !ctx.Repo.IsWriter() {
 		ctx.Status(403)
 		return
diff --git a/routers/api/v1/repo/milestone.go b/routers/api/v1/repo/milestone.go
index ef32ed8989..0e597a9db0 100644
--- a/routers/api/v1/repo/milestone.go
+++ b/routers/api/v1/repo/milestone.go
@@ -15,6 +15,14 @@ import (
 
 // ListMilestones list all the milestones for a repository
 func ListMilestones(ctx *context.APIContext) {
+	// swagger:operation GET /repos/{owner}/{repo}/milestones/{id} issue issueGetMilestone
+	// ---
+	// summary: Get a milestone
+	// produces:
+	// - application/json
+	// responses:
+	//   "200":
+	//     "$ref": "#/responses/Milestone"
 	milestones, err := models.GetMilestonesByRepoID(ctx.Repo.Repository.ID)
 	if err != nil {
 		ctx.Error(500, "GetMilestonesByRepoID", err)
@@ -30,6 +38,41 @@ func ListMilestones(ctx *context.APIContext) {
 
 // GetMilestone get a milestone for a repository
 func GetMilestone(ctx *context.APIContext) {
+	// swagger:operation GET /repos/{owner}/{repo}/milestones issue issueGetMilestones
+	// ---
+	// summary: Get all of a repository's milestones
+	// produces:
+	// - application/json
+	// parameters:
+	// - name: owner
+	//   in: path
+	//   description: owner of the repo
+	//   type: string
+	//   required: true
+	// - name: repo
+	//   in: path
+	//   description: name of the repo
+	//   type: string
+	//   required: true
+	// parameters:
+	// - name: owner
+	//   in: path
+	//   description: owner of the repo
+	//   type: string
+	//   required: true
+	// - name: repo
+	//   in: path
+	//   description: name of the repo
+	//   type: string
+	//   required: true
+	// - name: id
+	//   in: path
+	//   description: id of the milestone to get
+	//   type: integer
+	//   required: true
+	// responses:
+	//   "200":
+	//     "$ref": "#/responses/MilestoneList"
 	milestone, err := models.GetMilestoneByRepoID(ctx.Repo.Repository.ID, ctx.ParamsInt64(":id"))
 	if err != nil {
 		if models.IsErrMilestoneNotExist(err) {
@@ -44,6 +87,31 @@ func GetMilestone(ctx *context.APIContext) {
 
 // CreateMilestone create a milestone for a repository
 func CreateMilestone(ctx *context.APIContext, form api.CreateMilestoneOption) {
+	// swagger:operation POST /repos/{owner}/{repo}/milestones issue issueCreateMilestone
+	// ---
+	// summary: Create a milestone
+	// consumes:
+	// - application/json
+	// produces:
+	// - application/json
+	// parameters:
+	// - name: owner
+	//   in: path
+	//   description: owner of the repo
+	//   type: string
+	//   required: true
+	// - name: repo
+	//   in: path
+	//   description: name of the repo
+	//   type: string
+	//   required: true
+	// - name: body
+	//   in: body
+	//   schema:
+	//     "$ref": "#/definitions/CreateMilestoneOption"
+	// responses:
+	//   "201":
+	//     "$ref": "#/responses/Milestone"
 	if form.Deadline == nil {
 		defaultDeadline, _ := time.ParseInLocation("2006-01-02", "9999-12-31", time.Local)
 		form.Deadline = &defaultDeadline
@@ -65,6 +133,31 @@ func CreateMilestone(ctx *context.APIContext, form api.CreateMilestoneOption) {
 
 // EditMilestone modify a milestone for a repository
 func EditMilestone(ctx *context.APIContext, form api.EditMilestoneOption) {
+	// swagger:operation PATCH /repos/{owner}/{repo}/milestones/{id} issue issueEditMilestone
+	// ---
+	// summary: Update a milestone
+	// consumes:
+	// - application/json
+	// produces:
+	// - application/json
+	// parameters:
+	// - name: owner
+	//   in: path
+	//   description: owner of the repo
+	//   type: string
+	//   required: true
+	// - name: repo
+	//   in: path
+	//   description: name of the repo
+	//   type: string
+	//   required: true
+	// - name: body
+	//   in: body
+	//   schema:
+	//     "$ref": "#/definitions/EditMilestoneOption"
+	// responses:
+	//   "200":
+	//     "$ref": "#/responses/Milestone"
 	milestone, err := models.GetMilestoneByRepoID(ctx.Repo.Repository.ID, ctx.ParamsInt64(":id"))
 	if err != nil {
 		if models.IsErrMilestoneNotExist(err) {
@@ -94,6 +187,28 @@ func EditMilestone(ctx *context.APIContext, form api.EditMilestoneOption) {
 
 // DeleteMilestone delete a milestone for a repository
 func DeleteMilestone(ctx *context.APIContext) {
+	// swagger:operation DELETE /repos/{owner}/{repo}/milestones/{id} issue issueDeleteMilestone
+	// ---
+	// summary: Delete a milestone
+	// parameters:
+	// - name: owner
+	//   in: path
+	//   description: owner of the repo
+	//   type: string
+	//   required: true
+	// - name: repo
+	//   in: path
+	//   description: name of the repo
+	//   type: string
+	//   required: true
+	// - name: body
+	//   in: path
+	//   description: id of the milestone to delete
+	//   type: integer
+	//   required: true
+	// responses:
+	//   "204":
+	//     "$ref": "#/responses/empty"
 	if err := models.DeleteMilestoneByRepoID(ctx.Repo.Repository.ID, ctx.ParamsInt64(":id")); err != nil {
 		ctx.Error(500, "DeleteMilestoneByRepoID", err)
 		return
diff --git a/routers/api/v1/repo/pull.go b/routers/api/v1/repo/pull.go
index d1b73c6cf7..50b864e323 100644
--- a/routers/api/v1/repo/pull.go
+++ b/routers/api/v1/repo/pull.go
@@ -18,6 +18,25 @@ import (
 
 // ListPullRequests returns a list of all PRs
 func ListPullRequests(ctx *context.APIContext, form api.ListPullRequestsOptions) {
+	// swagger:operation GET /repos/{owner}/{repo}/pulls repository repoListPullRequests
+	// ---
+	// summary: List a repo's pull requests
+	// produces:
+	// - application/json
+	// parameters:
+	// - name: owner
+	//   in: path
+	//   description: owner of the repo
+	//   type: string
+	//   required: true
+	// - name: repo
+	//   in: path
+	//   description: name of the repo
+	//   type: string
+	//   required: true
+	// responses:
+	//   "200":
+	//     "$ref": "#/responses/PullRequestList"
 	prs, maxResults, err := models.PullRequests(ctx.Repo.Repository.ID, &models.PullRequestsOptions{
 		Page:        ctx.QueryInt("page"),
 		State:       ctx.QueryTrim("state"),
@@ -58,6 +77,30 @@ func ListPullRequests(ctx *context.APIContext, form api.ListPullRequestsOptions)
 
 // GetPullRequest returns a single PR based on index
 func GetPullRequest(ctx *context.APIContext) {
+	// swagger:operation GET /repos/{owner}/{repo}/pulls/{index} repository repoGetPullRequest
+	// ---
+	// summary: Get a pull request
+	// produces:
+	// - application/json
+	// parameters:
+	// - name: owner
+	//   in: path
+	//   description: owner of the repo
+	//   type: string
+	//   required: true
+	// - name: repo
+	//   in: path
+	//   description: name of the repo
+	//   type: string
+	//   required: true
+	// - name: index
+	//   in: path
+	//   description: index of the pull request to get
+	//   type: integer
+	//   required: true
+	// responses:
+	//   "200":
+	//     "$ref": "#/responses/PullRequest"
 	pr, err := models.GetPullRequestByIndex(ctx.Repo.Repository.ID, ctx.ParamsInt64(":index"))
 	if err != nil {
 		if models.IsErrPullRequestNotExist(err) {
@@ -81,6 +124,31 @@ func GetPullRequest(ctx *context.APIContext) {
 
 // CreatePullRequest does what it says
 func CreatePullRequest(ctx *context.APIContext, form api.CreatePullRequestOption) {
+	// swagger:operation POST /repos/{owner}/{repo}/pulls repository repoCreatePullRequest
+	// ---
+	// summary: Create a pull request
+	// consumes:
+	// - application/json
+	// produces:
+	// - application/json
+	// parameters:
+	// - name: owner
+	//   in: path
+	//   description: owner of the repo
+	//   type: string
+	//   required: true
+	// - name: repo
+	//   in: path
+	//   description: name of the repo
+	//   type: string
+	//   required: true
+	// - name: body
+	//   in: body
+	//   schema:
+	//     "$ref": "#/definitions/CreatePullRequestOption"
+	// responses:
+	//   "201":
+	//     "$ref": "#/responses/PullRequest"
 	var (
 		repo        = ctx.Repo.Repository
 		labelIDs    []int64
@@ -204,6 +272,36 @@ func CreatePullRequest(ctx *context.APIContext, form api.CreatePullRequestOption
 
 // EditPullRequest does what it says
 func EditPullRequest(ctx *context.APIContext, form api.EditPullRequestOption) {
+	// swagger:operation PATCH /repos/{owner}/{repo}/pulls/{index} repository repoEditPullRequest
+	// ---
+	// summary: Update a pull request
+	// consumes:
+	// - application/json
+	// produces:
+	// - application/json
+	// parameters:
+	// - name: owner
+	//   in: path
+	//   description: owner of the repo
+	//   type: string
+	//   required: true
+	// - name: repo
+	//   in: path
+	//   description: name of the repo
+	//   type: string
+	//   required: true
+	// - name: index
+	//   in: path
+	//   description: index of the pull request to edit
+	//   type: integer
+	//   required: true
+	// - name: body
+	//   in: body
+	//   schema:
+	//     "$ref": "#/definitions/EditPullRequestOption"
+	// responses:
+	//   "201":
+	//     "$ref": "#/responses/PullRequest"
 	pr, err := models.GetPullRequestByIndex(ctx.Repo.Repository.ID, ctx.ParamsInt64(":index"))
 	if err != nil {
 		if models.IsErrPullRequestNotExist(err) {
@@ -283,13 +381,42 @@ func EditPullRequest(ctx *context.APIContext, form api.EditPullRequestOption) {
 		return
 	}
 
+	// TODO this should be 200, not 201
 	ctx.JSON(201, pr.APIFormat())
 }
 
 // IsPullRequestMerged checks if a PR exists given an index
-//  - Returns 204 if it exists
-//    Otherwise 404
 func IsPullRequestMerged(ctx *context.APIContext) {
+	// swagger:operation GET /repos/{owner}/{repo}/pulls/{index}/merge repository repoPullRequestIsMerged
+	// ---
+	// summary: Check if a pull request has been merged
+	// produces:
+	// - application/json
+	// parameters:
+	// - name: owner
+	//   in: path
+	//   description: owner of the repo
+	//   type: string
+	//   required: true
+	// - name: repo
+	//   in: path
+	//   description: name of the repo
+	//   type: string
+	//   required: true
+	// - name: index
+	//   in: path
+	//   description: index of the pull request
+	//   type: integer
+	//   required: true
+	// responses:
+	//   "204":
+	//     description: pull request has been merged
+	//     schema:
+	//       "$ref": "#/responses/empty"
+	//   "404":
+	//     description: pull request has not been merged
+	//     schema:
+	//       "$ref": "#/responses/empty"
 	pr, err := models.GetPullRequestByIndex(ctx.Repo.Repository.ID, ctx.ParamsInt64(":index"))
 	if err != nil {
 		if models.IsErrPullRequestNotExist(err) {
@@ -308,6 +435,32 @@ func IsPullRequestMerged(ctx *context.APIContext) {
 
 // MergePullRequest merges a PR given an index
 func MergePullRequest(ctx *context.APIContext) {
+	// swagger:operation POST /repos/{owner}/{repo}/pulls/{index}/merge repository repoMergePullRequest
+	// ---
+	// summary: Merge a pull request
+	// produces:
+	// - application/json
+	// parameters:
+	// - name: owner
+	//   in: path
+	//   description: owner of the repo
+	//   type: string
+	//   required: true
+	// - name: repo
+	//   in: path
+	//   description: name of the repo
+	//   type: string
+	//   required: true
+	// - name: index
+	//   in: path
+	//   description: index of the pull request to merge
+	//   type: integer
+	//   required: true
+	// responses:
+	//   "200":
+	//     "$ref": "#/responses/empty"
+	//   "405":
+	//     "$ref": "#/responses/empty"
 	pr, err := models.GetPullRequestByIndex(ctx.Repo.Repository.ID, ctx.ParamsInt64(":index"))
 	if err != nil {
 		if models.IsErrPullRequestNotExist(err) {
diff --git a/routers/api/v1/repo/release.go b/routers/api/v1/repo/release.go
index 78289a6a2a..17cddc5652 100644
--- a/routers/api/v1/repo/release.go
+++ b/routers/api/v1/repo/release.go
@@ -13,6 +13,30 @@ import (
 
 // GetRelease get a single release of a repository
 func GetRelease(ctx *context.APIContext) {
+	// swagger:operation GET /repos/{owner}/{repo}/releases repository repoGetRelease
+	// ---
+	// summary: Get a release
+	// produces:
+	// - application/json
+	// parameters:
+	// - name: owner
+	//   in: path
+	//   description: owner of the repo
+	//   type: string
+	//   required: true
+	// - name: repo
+	//   in: path
+	//   description: name of the repo
+	//   type: string
+	//   required: true
+	// - name: repo
+	//   in: path
+	//   description: id of the release to get
+	//   type: integer
+	//   required: true
+	// responses:
+	//   "200":
+	//     "$ref": "#/responses/Release"
 	id := ctx.ParamsInt64(":id")
 	release, err := models.GetReleaseByID(id)
 	if err != nil {
@@ -32,6 +56,25 @@ func GetRelease(ctx *context.APIContext) {
 
 // ListReleases list a repository's releases
 func ListReleases(ctx *context.APIContext) {
+	// swagger:operation GET /repos/{owner}/{repo}/releases repository repoListReleases
+	// ---
+	// summary: List a repo's releases
+	// produces:
+	// - application/json
+	// parameters:
+	// - name: owner
+	//   in: path
+	//   description: owner of the repo
+	//   type: string
+	//   required: true
+	// - name: repo
+	//   in: path
+	//   description: name of the repo
+	//   type: string
+	//   required: true
+	// responses:
+	//   "200":
+	//     "$ref": "#/responses/ReleaseList"
 	releases, err := models.GetReleasesByRepoID(ctx.Repo.Repository.ID, models.FindReleasesOptions{
 		IncludeDrafts: ctx.Repo.AccessMode >= models.AccessModeWrite,
 		IncludeTags:   false,
@@ -53,6 +96,31 @@ func ListReleases(ctx *context.APIContext) {
 
 // CreateRelease create a release
 func CreateRelease(ctx *context.APIContext, form api.CreateReleaseOption) {
+	// swagger:operation GET /repos/{owner}/{repo}/releases repository repoCreateRelease
+	// ---
+	// summary: Create a release
+	// consumes:
+	// - application/json
+	// produces:
+	// - application/json
+	// parameters:
+	// - name: owner
+	//   in: path
+	//   description: owner of the repo
+	//   type: string
+	//   required: true
+	// - name: repo
+	//   in: path
+	//   description: name of the repo
+	//   type: string
+	//   required: true
+	// - name: body
+	//   in: body
+	//   schema:
+	//     "$ref": "#/definitions/CreateReleaseOption"
+	// responses:
+	//   "201":
+	//     "$ref": "#/responses/Release"
 	if ctx.Repo.AccessMode < models.AccessModeWrite {
 		ctx.Status(403)
 		return
@@ -110,6 +178,36 @@ func CreateRelease(ctx *context.APIContext, form api.CreateReleaseOption) {
 
 // EditRelease edit a release
 func EditRelease(ctx *context.APIContext, form api.EditReleaseOption) {
+	// swagger:operation PATCH /repos/{owner}/{repo}/releases/{id} repository repoEditRelease
+	// ---
+	// summary: Update a release
+	// consumes:
+	// - application/json
+	// produces:
+	// - application/json
+	// parameters:
+	// - name: owner
+	//   in: path
+	//   description: owner of the repo
+	//   type: string
+	//   required: true
+	// - name: repo
+	//   in: path
+	//   description: name of the repo
+	//   type: string
+	//   required: true
+	// - name: id
+	//   in: path
+	//   description: id of the release to edit
+	//   type: integer
+	//   required: true
+	// - name: body
+	//   in: body
+	//   schema:
+	//     "$ref": "#/definitions/EditReleaseOption"
+	// responses:
+	//   "200":
+	//     "$ref": "#/responses/Release"
 	if ctx.Repo.AccessMode < models.AccessModeWrite {
 		ctx.Status(403)
 		return
@@ -163,6 +261,28 @@ func EditRelease(ctx *context.APIContext, form api.EditReleaseOption) {
 
 // DeleteRelease delete a release from a repository
 func DeleteRelease(ctx *context.APIContext) {
+	// swagger:operation DELETE /repos/{owner}/{repo}/releases/{id} repository repoDeleteRelease
+	// ---
+	// summary: Delete a release
+	// parameters:
+	// - name: owner
+	//   in: path
+	//   description: owner of the repo
+	//   type: string
+	//   required: true
+	// - name: repo
+	//   in: path
+	//   description: name of the repo
+	//   type: string
+	//   required: true
+	// - name: id
+	//   in: path
+	//   description: id of the release to delete
+	//   type: integer
+	//   required: true
+	// responses:
+	//   "204":
+	//     "$ref": "#/responses/empty"
 	if ctx.Repo.AccessMode < models.AccessModeWrite {
 		ctx.Status(403)
 		return
diff --git a/routers/api/v1/repo/repo.go b/routers/api/v1/repo/repo.go
index 34f4c5fa16..36e644373c 100644
--- a/routers/api/v1/repo/repo.go
+++ b/routers/api/v1/repo/repo.go
@@ -20,45 +20,40 @@ import (
 	"code.gitea.io/gitea/routers/api/v1/convert"
 )
 
-// SearchRepoOption options when searching repositories
-// swagger:parameters repoSearch
-type SearchRepoOption struct { // TODO: Move SearchRepoOption to Gitea SDK
-	// Keyword to search
-	//
-	// in: query
-	Keyword string `json:"q"`
-	// Repository owner to search
-	//
-	// in: query
-	OwnerID int64 `json:"uid"`
-	// Limit of result
-	//
-	// maximum: setting.ExplorePagingNum
-	// in: query
-	PageSize int `json:"limit"`
-	// Type of repository to search, related to owner
-	//
-	// in: query
-	SearchMode string `json:"mode"`
-	// Search only owners repositories
-	// Has effect only if owner is provided and mode is not "collaborative"
-	//
-	// in: query
-	OwnerExclusive bool `json:"exclusive"`
-}
-
 // Search repositories via options
 func Search(ctx *context.APIContext) {
-	// swagger:route GET /repos/search repository repoSearch
-	//
-	//     Produces:
-	//     - application/json
-	//
-	//     Responses:
-	//       200: SearchResults
-	//       422: validationError
-	//       500: SearchError
-
+	// swagger:operation GET /repos/search repository repoSearch
+	// ---
+	// summary: Search for repositories
+	// produces:
+	// - application/json
+	// parameters:
+	// - name: q
+	//   in: query
+	//   description: keyword
+	//   type: string
+	// - name: uid
+	//   in: query
+	//   description: if provided, will return only repos owned by the user with the given id
+	//   type: integer
+	// - name: limit
+	//   in: query
+	//   description: maximum number of repos to return
+	//   type: integer
+	// - name: mode
+	//   in: query
+	//   description: type of repository to search for. Supported values are
+	//                "fork", "source", "mirror" and "collaborative"
+	//   type: string
+	// - name: exclusive
+	//   in: query
+	//   description: only search for repositories owned by the authenticated user
+	//   type: boolean
+	// responses:
+	//   "200":
+	//     "$ref": "#/responses/SearchResults"
+	//   "422":
+	//     "$ref": "#/responses/validationError"
 	opts := &models.SearchRepoOptions{
 		Keyword:     strings.Trim(ctx.Query("q"), " "),
 		OwnerID:     ctx.QueryInt64("uid"),
@@ -187,22 +182,23 @@ func CreateUserRepo(ctx *context.APIContext, owner *models.User, opt api.CreateR
 
 // Create one repository of mine
 func Create(ctx *context.APIContext, opt api.CreateRepoOption) {
-	// swagger:route POST /user/repos repository user createCurrentUserRepo
-	//
-	//     Consumes:
-	//     - application/json
-	//
-	//     Produces:
-	//     - application/json
-	//
-	//     Responses:
-	//       201: Repository
-	//       403: forbidden
-	//       422: validationError
-	//       500: error
-
-	// Shouldn't reach this condition, but just in case.
+	// swagger:operation POST /user/repos repository user createCurrentUserRepo
+	// ---
+	// summary: Create a repository
+	// consumes:
+	// - application/json
+	// produces:
+	// - application/json
+	// parameters:
+	// - name: body
+	//   in: body
+	//   schema:
+	//     "$ref": "#/definitions/CreateRepoOption"
+	// responses:
+	//   "201":
+	//     "$ref": "#/responses/Repository"
 	if ctx.User.IsOrganization() {
+		// Shouldn't reach this condition, but just in case.
 		ctx.Error(422, "", "not allowed creating repository for organization")
 		return
 	}
@@ -211,20 +207,30 @@ func Create(ctx *context.APIContext, opt api.CreateRepoOption) {
 
 // CreateOrgRepo create one repository of the organization
 func CreateOrgRepo(ctx *context.APIContext, opt api.CreateRepoOption) {
-	// swagger:route POST /org/{org}/repos organization createOrgRepo
-	//
-	//     Consumes:
-	//     - application/json
-	//
-	//     Produces:
-	//     - application/json
-	//
-	//     Responses:
-	//       201: Repository
-	//       422: validationError
-	//       403: forbidden
-	//       500: error
-
+	// swagger:operation POST /org/{org}/repos organization createOrgRepo
+	// ---
+	// summary: Create a repository in an organization
+	// consumes:
+	// - application/json
+	// produces:
+	// - application/json
+	// parameters:
+	// - name: org
+	//   in: path
+	//   description: name of organization
+	//   type: string
+	//   required: true
+	// - name: body
+	//   in: body
+	//   schema:
+	//     "$ref": "#/definitions/CreateRepoOption"
+	// responses:
+	//   "201":
+	//     "$ref": "#/responses/Repository"
+	//   "422":
+	//     "$ref": "#/responses/validationError"
+	//   "403":
+	//     "$ref": "#/responses/forbidden"
 	org, err := models.GetOrgByName(ctx.Params(":org"))
 	if err != nil {
 		if models.IsErrOrgNotExist(err) {
@@ -244,19 +250,21 @@ func CreateOrgRepo(ctx *context.APIContext, opt api.CreateRepoOption) {
 
 // Migrate migrate remote git repository to gitea
 func Migrate(ctx *context.APIContext, form auth.MigrateRepoForm) {
-	// swagger:route POST /repos/migrate repository repoMigrate
-	//
-	//     Consumes:
-	//     - application/json
-	//
-	//     Produces:
-	//     - application/json
-	//
-	//     Responses:
-	//       201: Repository
-	//       422: validationError
-	//       500: error
-
+	// swagger:operation POST /repos/migrate repository repoMigrate
+	// ---
+	// summary: Migrate a remote git repository
+	// consumes:
+	// - application/json
+	// produces:
+	// - application/json
+	// parameters:
+	// - name: body
+	//   in: body
+	//   schema:
+	//     "$ref": "#/definitions/MigrateRepoForm"
+	// responses:
+	//   "201":
+	//     "$ref": "#/responses/Repository"
 	ctxUser := ctx.User
 	// Not equal means context user is an organization,
 	// or is another user/organization if current user is admin.
@@ -329,29 +337,44 @@ func Migrate(ctx *context.APIContext, form auth.MigrateRepoForm) {
 
 // Get one repository
 func Get(ctx *context.APIContext) {
-	// swagger:route GET /repos/{username}/{reponame} repository repoGet
-	//
-	//     Produces:
-	//     - application/json
-	//
-	//     Responses:
-	//       200: Repository
-	//       500: error
-
+	// swagger:operation GET /repos/{owner}/{repo} repository repoGet
+	// ---
+	// summary: Get a repository
+	// produces:
+	// - application/json
+	// parameters:
+	// - name: owner
+	//   in: path
+	//   description: owner of the repo
+	//   type: string
+	//   required: true
+	// - name: repo
+	//   in: path
+	//   description: name of the repo
+	//   type: string
+	//   required: true
+	// responses:
+	//   "200":
+	//     "$ref": "#/responses/Repository"
 	ctx.JSON(200, ctx.Repo.Repository.APIFormat(ctx.Repo.AccessMode))
 }
 
 // GetByID returns a single Repository
 func GetByID(ctx *context.APIContext) {
-	// swagger:route GET /repositories/{id} repository repoGetByID
-	//
-	//     Produces:
-	//     - application/json
-	//
-	//     Responses:
-	//       200: Repository
-	//       500: error
-
+	// swagger:operation GET /repositories/{id} repository repoGetByID
+	// ---
+	// summary: Get a repository by id
+	// produces:
+	// - application/json
+	// parameters:
+	// - name: id
+	//   in: path
+	//   description: id of the repo to get
+	//   type: integer
+	//   required: true
+	// responses:
+	//   "200":
+	//     "$ref": "#/responses/Repository"
 	repo, err := models.GetRepositoryByID(ctx.ParamsInt64(":id"))
 	if err != nil {
 		if models.IsErrRepoNotExist(err) {
@@ -375,16 +398,27 @@ func GetByID(ctx *context.APIContext) {
 
 // Delete one repository
 func Delete(ctx *context.APIContext) {
-	// swagger:route DELETE /repos/{username}/{reponame} repository repoDelete
-	//
-	//     Produces:
-	//     - application/json
-	//
-	//     Responses:
-	//       204: empty
-	//       403: forbidden
-	//       500: error
-
+	// swagger:operation DELETE /repos/{owner}/{repo} repository repoDelete
+	// ---
+	// summary: Delete a repository
+	// produces:
+	// - application/json
+	// parameters:
+	// - name: owner
+	//   in: path
+	//   description: owner of the repo to delete
+	//   type: string
+	//   required: true
+	// - name: repo
+	//   in: path
+	//   description: name of the repo to delete
+	//   type: string
+	//   required: true
+	// responses:
+	//   "204":
+	//     "$ref": "#/responses/empty"
+	//   "403":
+	//     "$ref": "#/responses/forbidden"
 	if !ctx.Repo.IsAdmin() {
 		ctx.Error(403, "", "Must have admin rights")
 		return
@@ -408,15 +442,25 @@ func Delete(ctx *context.APIContext) {
 
 // MirrorSync adds a mirrored repository to the sync queue
 func MirrorSync(ctx *context.APIContext) {
-	// swagger:route POST /repos/{username}/{reponame}/mirror-sync repository repoMirrorSync
-	//
-	//     Produces:
-	//     - application/json
-	//
-	//     Responses:
-	//       200: empty
-	//       403: forbidden
-
+	// swagger:operation POST /repos/{owner}/{repo}/mirror-sync repository repoMirrorSync
+	// ---
+	// summary: Sync a mirrored repository
+	// produces:
+	// - application/json
+	// parameters:
+	// - name: owner
+	//   in: path
+	//   description: owner of the repo to sync
+	//   type: string
+	//   required: true
+	// - name: repo
+	//   in: path
+	//   description: name of the repo to sync
+	//   type: string
+	//   required: true
+	// responses:
+	//   "200":
+	//     "$ref": "#/responses/empty"
 	repo := ctx.Repo.Repository
 
 	if !ctx.Repo.IsWriter() {
diff --git a/routers/api/v1/repo/star.go b/routers/api/v1/repo/star.go
index 20e7e4e508..3500eaf421 100644
--- a/routers/api/v1/repo/star.go
+++ b/routers/api/v1/repo/star.go
@@ -12,6 +12,25 @@ import (
 
 // ListStargazers list a repository's stargazers
 func ListStargazers(ctx *context.APIContext) {
+	// swagger:operation GET /repos/{owner}/{repo}/stargazers repository repoListStargazers
+	// ---
+	// summary: List a repo's stargazers
+	// produces:
+	// - application/json
+	// parameters:
+	// - name: owner
+	//   in: path
+	//   description: owner of the repo
+	//   type: string
+	//   required: true
+	// - name: repo
+	//   in: path
+	//   description: name of the repo
+	//   type: string
+	//   required: true
+	// responses:
+	//   "200":
+	//     "$ref": "#/responses/UserList"
 	stargazers, err := ctx.Repo.Repository.GetStargazers(-1)
 	if err != nil {
 		ctx.Error(500, "GetStargazers", err)
diff --git a/routers/api/v1/repo/status.go b/routers/api/v1/repo/status.go
index e4cc20a50b..7f7ef1ae32 100644
--- a/routers/api/v1/repo/status.go
+++ b/routers/api/v1/repo/status.go
@@ -14,6 +14,34 @@ import (
 
 // NewCommitStatus creates a new CommitStatus
 func NewCommitStatus(ctx *context.APIContext, form api.CreateStatusOption) {
+	// swagger:operation POST /repos/{owner}/{repo}/statuses/{sha} repository repoCreateStatus
+	// ---
+	// summary: Create a commit status
+	// produces:
+	// - application/json
+	// parameters:
+	// - name: owner
+	//   in: path
+	//   description: owner of the repo
+	//   type: string
+	//   required: true
+	// - name: repo
+	//   in: path
+	//   description: name of the repo
+	//   type: string
+	//   required: true
+	// - name: sha
+	//   in: path
+	//   description: sha of the commit
+	//   type: string
+	//   required: true
+	// - name: body
+	//   in: body
+	//   schema:
+	//     "$ref": "#/definitions/CreateStatusOption"
+	// responses:
+	//   "200":
+	//     "$ref": "#/responses/StatusList"
 	sha := ctx.Params("sha")
 	if len(sha) == 0 {
 		sha = ctx.Params("ref")
@@ -43,10 +71,63 @@ func NewCommitStatus(ctx *context.APIContext, form api.CreateStatusOption) {
 
 // GetCommitStatuses returns all statuses for any given commit hash
 func GetCommitStatuses(ctx *context.APIContext) {
-	sha := ctx.Params("sha")
-	if len(sha) == 0 {
-		sha = ctx.Params("ref")
-	}
+	// swagger:operation GET /repos/{owner}/{repo}/statuses/{sha} repository repoListStatuses
+	// ---
+	// summary: Get a commit's statuses
+	// produces:
+	// - application/json
+	// parameters:
+	// - name: owner
+	//   in: path
+	//   description: owner of the repo
+	//   type: string
+	//   required: true
+	// - name: repo
+	//   in: path
+	//   description: name of the repo
+	//   type: string
+	//   required: true
+	// - name: sha
+	//   in: path
+	//   description: sha of the commit
+	//   type: string
+	//   required: true
+	// responses:
+	//   "200":
+	//     "$ref": "#/responses/StatusList"
+	getCommitStatuses(ctx, ctx.Params("sha"))
+}
+
+// GetCommitStatusesByRef returns all statuses for any given commit ref
+func GetCommitStatusesByRef(ctx *context.APIContext) {
+	// swagger:operation GET /repos/{owner}/{repo}/commits/{ref}/statuses repository repoListStatusesByRef
+	// ---
+	// summary: Get a commit's statuses, by branch/tag/commit reference
+	// produces:
+	// - application/json
+	// parameters:
+	// - name: owner
+	//   in: path
+	//   description: owner of the repo
+	//   type: string
+	//   required: true
+	// - name: repo
+	//   in: path
+	//   description: name of the repo
+	//   type: string
+	//   required: true
+	// - name: ref
+	//   in: path
+	//   description: name of branch/tag/commit
+	//   type: string
+	//   required: true
+	// responses:
+	//   "200":
+	//     "$ref": "#/responses/StatusList"
+	getCommitStatuses(ctx, ctx.Params("ref"))
+}
+
+func getCommitStatuses(ctx *context.APIContext, sha string) {
 	if len(sha) == 0 {
 		ctx.Error(400, "ref/sha not given", nil)
 		return
@@ -78,12 +159,33 @@ type combinedCommitStatus struct {
 	URL        string                   `json:"url"`
 }
 
-// GetCombinedCommitStatus returns the combined status for any given commit hash
-func GetCombinedCommitStatus(ctx *context.APIContext) {
-	sha := ctx.Params("sha")
-	if len(sha) == 0 {
-		sha = ctx.Params("ref")
-	}
+// GetCombinedCommitStatusByRef returns the combined status for any given commit hash
+func GetCombinedCommitStatusByRef(ctx *context.APIContext) {
+	// swagger:operation GET /repos/{owner}/{repo}/commits/{ref}/statuses repository repoGetCombinedStatusByRef
+	// ---
+	// summary: Get a commit's combined status, by branch/tag/commit reference
+	// produces:
+	// - application/json
+	// parameters:
+	// - name: owner
+	//   in: path
+	//   description: owner of the repo
+	//   type: string
+	//   required: true
+	// - name: repo
+	//   in: path
+	//   description: name of the repo
+	//   type: string
+	//   required: true
+	// - name: ref
+	//   in: path
+	//   description: name of branch/tag/commit
+	//   type: string
+	//   required: true
+	// responses:
+	//   "200":
+	//     "$ref": "#/responses/Status"
+	sha := ctx.Params("ref")
 	if len(sha) == 0 {
 		ctx.Error(400, "ref/sha not given", nil)
 		return
diff --git a/routers/api/v1/repo/subscriber.go b/routers/api/v1/repo/subscriber.go
index d9d9a6c96d..737ae89f01 100644
--- a/routers/api/v1/repo/subscriber.go
+++ b/routers/api/v1/repo/subscriber.go
@@ -12,6 +12,25 @@ import (
 
 // ListSubscribers list a repo's subscribers (i.e. watchers)
 func ListSubscribers(ctx *context.APIContext) {
+	// swagger:operation GET /repos/{owner}/{repo}/subscribers repository repoListSubscribers
+	// ---
+	// summary: List a repo's watchers
+	// produces:
+	// - application/json
+	// parameters:
+	// - name: owner
+	//   in: path
+	//   description: owner of the repo
+	//   type: string
+	//   required: true
+	// - name: repo
+	//   in: path
+	//   description: name of the repo
+	//   type: string
+	//   required: true
+	// responses:
+	//   "200":
+	//     "$ref": "#/responses/UserList"
 	subscribers, err := ctx.Repo.Repository.GetWatchers(0)
 	if err != nil {
 		ctx.Error(500, "GetWatchers", err)
diff --git a/routers/api/v1/swagger/issue.go b/routers/api/v1/swagger/issue.go
new file mode 100644
index 0000000000..1ebb17b249
--- /dev/null
+++ b/routers/api/v1/swagger/issue.go
@@ -0,0 +1,69 @@
+// Copyright 2017 The Gitea Authors. All rights reserved.
+// Use of this source code is governed by a MIT-style
+// license that can be found in the LICENSE file.
+
+package swagger
+
+import (
+	api "code.gitea.io/sdk/gitea"
+)
+
+// swagger:response Issue
+type swaggerResponseIssue struct {
+	// in:body
+	Body api.Issue `json:"body"`
+}
+
+// swagger:response IssueList
+type swaggerResponseIssueList struct {
+	// in:body
+	Body []api.Issue `json:"body"`
+}
+
+// swagger:response Comment
+type swaggerResponseComment struct {
+	// in:body
+	Body api.Comment `json:"body"`
+}
+
+// swagger:response CommentList
+type swaggerResponseCommentList struct {
+	// in:body
+	Body []api.Comment `json:"body"`
+}
+
+// swagger:response Label
+type swaggerResponseLabel struct {
+	// in:body
+	Body api.Label `json:"body"`
+}
+
+// swagger:response LabelList
+type swaggerResponseLabelList struct {
+	// in:body
+	Body []api.Label `json:"body"`
+}
+
+// swagger:response Milestone
+type swaggerResponseMilestone struct {
+	// in:body
+	Body api.Milestone `json:"body"`
+}
+
+// swagger:response MilestoneList
+type swaggerResponseMilestoneList struct {
+	// in:body
+	Body []api.Milestone `json:"body"`
+}
+
+// swagger:response TrackedTime
+type swaggerResponseTrackedTime struct {
+	// in:body
+	Body api.TrackedTime `json:"body"`
+}
+
+// swagger:response TrackedTimeList
+type swaggerResponseTrackedTimeList struct {
+	// in:body
+	Body []api.TrackedTime `json:"body"`
+}
diff --git a/routers/api/v1/swagger/key.go b/routers/api/v1/swagger/key.go
new file mode 100644
index 0000000000..344d54c878
--- /dev/null
+++ b/routers/api/v1/swagger/key.go
@@ -0,0 +1,45 @@
+// Copyright 2017 The Gitea Authors. All rights reserved.
+// Use of this source code is governed by a MIT-style
+// license that can be found in the LICENSE file.
+
+package swagger
+
+import (
+	api "code.gitea.io/sdk/gitea"
+)
+
+// swagger:response PublicKey
+type swaggerResponsePublicKey struct {
+	// in:body
+	Body api.PublicKey `json:"body"`
+}
+
+// swagger:response PublicKeyList
+type swaggerResponsePublicKeyList struct {
+	// in:body
+	Body []api.PublicKey `json:"body"`
+}
+
+// swagger:response GPGKey
+type swaggerResponseGPGKey struct {
+	// in:body
+	Body api.GPGKey `json:"body"`
+}
+
+// swagger:response GPGKeyList
+type swaggerResponseGPGKeyList struct {
+	// in:body
+	Body []api.GPGKey `json:"body"`
+}
+
+// swagger:response DeployKey
+type swaggerResponseDeployKey struct {
+	// in:body
+	Body api.DeployKey `json:"body"`
+}
+
+// swagger:response DeployKeyList
+type swaggerResponseDeployKeyList struct {
+	// in:body
+	Body []api.DeployKey `json:"body"`
+}
diff --git a/routers/api/v1/swagger/misc.go b/routers/api/v1/swagger/misc.go
new file mode 100644
index 0000000000..8ec0d53a79
--- /dev/null
+++ b/routers/api/v1/swagger/misc.go
@@ -0,0 +1,15 @@
+// Copyright 2017 The Gitea Authors. All rights reserved.
+// Use of this source code is governed by a MIT-style
+// license that can be found in the LICENSE file.
+
+package swagger
+
+import (
+	api "code.gitea.io/sdk/gitea"
+)
+
+// swagger:response ServerVersion
+type swaggerResponseServerVersion struct {
+	// in:body
+	Body api.ServerVersion `json:"body"`
+}
diff --git a/routers/api/v1/swagger/options.go b/routers/api/v1/swagger/options.go
new file mode 100644
index 0000000000..31251eb3e2
--- /dev/null
+++ b/routers/api/v1/swagger/options.go
@@ -0,0 +1,66 @@
+// Copyright 2017 The Gitea Authors. All rights reserved.
+// Use of this source code is governed by a MIT-style
+// license that can be found in the LICENSE file.
+
+package swagger
+
+import (
+	"code.gitea.io/gitea/modules/auth"
+	api "code.gitea.io/sdk/gitea"
+)
+
+// not actually a response, just a hack to get go-swagger to include definitions
+// of the various XYZOption structs
+
+// swagger:response parameterBodies
+type swaggerParameterBodies struct {
+	AddCollaboratorOption api.AddCollaboratorOption
+
+	CreateEmailOption api.CreateEmailOption
+	DeleteEmailOption api.DeleteEmailOption
+
+	CreateHookOption api.CreateHookOption
+	EditHookOption   api.EditHookOption
+
+	CreateIssueOption api.CreateIssueOption
+	EditIssueOption   api.EditIssueOption
+
+	CreateIssueCommentOption api.CreateIssueCommentOption
+	EditIssueCommentOption   api.EditIssueCommentOption
+
+	IssueLabelsOption api.IssueLabelsOption
+
+	CreateKeyOption api.CreateKeyOption
+
+	CreateLabelOption api.CreateLabelOption
+	EditLabelOption   api.EditLabelOption
+
+	MarkdownOption api.MarkdownOption
+
+	CreateMilestoneOption api.CreateMilestoneOption
+	EditMilestoneOption   api.EditMilestoneOption
+
+	CreateOrgOption api.CreateOrgOption
+	EditOrgOption   api.EditOrgOption
+
+	CreatePullRequestOption api.CreatePullRequestOption
+	EditPullRequestOption   api.EditPullRequestOption
+
+	CreateReleaseOption api.CreateReleaseOption
+	EditReleaseOption   api.EditReleaseOption
+
+	CreateRepoOption api.CreateRepoOption
+	CreateForkOption api.CreateForkOption
+
+	CreateStatusOption api.CreateStatusOption
+
+	CreateTeamOption api.CreateTeamOption
+	EditTeamOption   api.EditTeamOption
+
+	AddTimeOption api.AddTimeOption
+
+	CreateUserOption api.CreateUserOption
+	EditUserOption   api.EditUserOption
+
+	MigrateRepoForm auth.MigrateRepoForm
+}
diff --git a/routers/api/v1/swagger/org.go b/routers/api/v1/swagger/org.go
new file mode 100644
index 0000000000..46bd56646b
--- /dev/null
+++ b/routers/api/v1/swagger/org.go
@@ -0,0 +1,33 @@
+// Copyright 2017 The Gitea Authors. All rights reserved.
+// Use of this source code is governed by a MIT-style
+// license that can be found in the LICENSE file.
+
+package swagger
+
+import (
+	api "code.gitea.io/sdk/gitea"
+)
+
+// swagger:response Organization
+type swaggerResponseOrganization struct {
+	// in:body
+	Body api.Organization `json:"body"`
+}
+
+// swagger:response OrganizationList
+type swaggerResponseOrganizationList struct {
+	// in:body
+	Body []api.Organization `json:"body"`
+}
+
+// swagger:response Team
+type swaggerResponseTeam struct {
+	// in:body
+	Body api.Team `json:"body"`
+}
+
+// swagger:response TeamList
+type swaggerResponseTeamList struct {
+	// in:body
+	Body []api.Team `json:"body"`
+}
diff --git a/routers/api/v1/swagger/repo.go b/routers/api/v1/swagger/repo.go
new file mode 100644
index 0000000000..703f7d18dd
--- /dev/null
+++ b/routers/api/v1/swagger/repo.go
@@ -0,0 +1,92 @@
+// Copyright 2017 The Gitea Authors. All rights reserved.
+// Use of this source code is governed by a MIT-style
+// license that can be found in the LICENSE file.
+
+package swagger
+
+import (
+	api "code.gitea.io/sdk/gitea"
+)
+
+// swagger:response Repository
+type swaggerResponseRepository struct {
+	// in:body
+	Body api.Repository `json:"body"`
+}
+
+// swagger:response RepositoryList
+type swaggerResponseRepositoryList struct {
+	// in:body
+	Body []api.Repository `json:"body"`
+}
+
+// swagger:response Branch
+type swaggerResponseBranch struct {
+	// in:body
+	Body api.Branch `json:"body"`
+}
+
+// swagger:response BranchList
+type swaggerResponseBranchList struct {
+	// in:body
+	Body []api.Branch `json:"body"`
+}
+
+// swagger:response Hook
+type swaggerResponseHook struct {
+	// in:body
+	Body []api.Branch `json:"body"`
+}
+
+// swagger:response HookList
+type swaggerResponseHookList struct {
+	// in:body
+	Body []api.Branch `json:"body"`
+}
+
+// swagger:response Release
+type swaggerResponseRelease struct {
+	// in:body
+	Body api.Release `json:"body"`
+}
+
+// swagger:response ReleaseList
+type swaggerResponseReleaseList struct {
+	// in:body
+	Body []api.Release `json:"body"`
+}
+
+// swagger:response PullRequest
+type swaggerResponsePullRequest struct {
+	// in:body
+	Body api.PullRequest `json:"body"`
+}
+
+// swagger:response PullRequestList
+type swaggerResponsePullRequestList struct {
+	// in:body
+	Body []api.PullRequest `json:"body"`
+}
+
+// swagger:response Status
+type swaggerResponseStatus struct {
+	// in:body
+	Body api.Status `json:"body"`
+}
+
+// swagger:response StatusList
+type swaggerResponseStatusList struct {
+	// in:body
+	Body []api.Status `json:"body"`
+}
+
+// swagger:response WatchInfo
+type swaggerResponseWatchInfo struct {
+	// in:body
+	Body api.WatchInfo `json:"body"`
+}
+
+// swagger:response SearchResults
+type swaggerResponseSearchResults struct {
+	Body api.SearchResults `json:"body"`
+}
diff --git a/routers/api/v1/swagger/user.go b/routers/api/v1/swagger/user.go
new file mode 100644
index 0000000000..2bb8f1b76b
--- /dev/null
+++ b/routers/api/v1/swagger/user.go
@@ -0,0 +1,33 @@
+// Copyright 2017 The Gitea Authors. All rights reserved.
+// Use of this source code is governed by a MIT-style
+// license that can be found in the LICENSE file.
+
+package swagger
+
+import (
+	api "code.gitea.io/sdk/gitea"
+)
+
+// swagger:response User
+type swaggerResponseUser struct {
+	// in:body
+	Body api.User `json:"body"`
+}
+
+// swagger:response UserList
+type swaggerResponseUserList struct {
+	// in:body
+	Body []api.User `json:"body"`
+}
+
+// swagger:response EmailList
+type swaggerResponseEmailList struct {
+	// in:body
+	Body []api.Email `json:"body"`
+}
+
+// swagger:model EditUserOption
+type swaggerModelEditUserOption struct {
+	// in:body
+	Options api.EditUserOption
+}
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)