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

Makefile

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

modules/auth/repo_form.go

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

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
+	// swagger:operation POST /admin/users/{username}/orgs admin adminCreateOrg
-	//
+	// ---
-	//     Consumes:
+	// summary: Create an organization
+	// consumes:
 	// - application/json
-	//
+	// produces:
-	//     Produces:
 	// - application/json
-	//
+	// parameters:
-	//     Responses:
+	// - name: username
-	//       201: Organization
+	//   in: path
-	//       403: forbidden
+	//   description: username of the user that will own the created organization
-	//       422: validationError
+	//   type: string
-	//       500: error
+	//   required: true
-
+	// responses:
+	//   "201":
+	//     "$ref": "#/responses/Organization"
+	//   "403":
+	//     "$ref": "#/responses/forbidden"
+	//   "422":
+	//     "$ref": "#/responses/validationError"
 	u := user.GetUserByParams(ctx)
 	if ctx.Written() {
 		return

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
+	// swagger:operation POST /admin/users/{username}/repos admin adminCreateRepo
-	//
+	// ---
-	//     Consumes:
+	// summary: Create a repository on behalf a user
+	// consumes:
 	// - application/json
-	//
+	// produces:
-	//     Produces:
 	// - application/json
-	//
+	// parameters:
-	//     Responses:
+	// - name: username
-	//       201: Repository
+	//   in: path
-	//       403: forbidden
+	//   description: username of the user. This user will own the created repository
-	//       422: validationError
+	//   type: string
-	//       500: error
+	//   required: true
-
+	// responses:
+	//   "201":
+	//     "$ref": "#/responses/Repository"
+	//   "403":
+	//     "$ref": "#/responses/forbidden"
+	//   "422":
+	//     "$ref": "#/responses/validationError"
 	owner := user.GetUserByParams(ctx)
 	if ctx.Written() {
 		return

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
+	// swagger:operation POST /admin/users admin adminCreateUser
-	//
+	// ---
-	//     Consumes:
+	// summary: Create a user
+	// consumes:
 	// - application/json
-	//
+	// produces:
-	//     Produces:
 	// - application/json
-	//
+	// parameters:
-	//     Responses:
+	// - name: body
-	//       201: User
+	//   in: body
-	//       403: forbidden
+	//   schema:
-	//       422: validationError
+	//     "$ref": "#/definitions/CreateUserOption"
-	//       500: error
+	// 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
+	// swagger:operation PATCH /admin/users/{username} admin adminEditUser
-	//
+	// ---
-	//     Consumes:
+	// summary: Edit an existing user
+	// consumes:
 	// - application/json
-	//
+	// produces:
-	//     Produces:
 	// - application/json
-	//
+	// parameters:
-	//     Responses:
+	// - name: username
-	//       200: User
+	//   in: path
-	//       403: forbidden
+	//   description: username of user to edit
-	//       422: validationError
+	//   type: string
-	//       500: error
+	//   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
+	// swagger:operation DELETE /admin/users/{username} admin adminDeleteUser
-	//
+	// ---
-	//     Produces:
+	// summary: Delete a user
+	// produces:
 	// - application/json
-	//
+	// parameters:
-	//     Responses:
+	// - name: username
-	//       204: empty
+	//   in: path
-	//       403: forbidden
+	//   description: username of user to delete
-	//       422: validationError
+	//   type: string
-	//       500: error
+	//   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
+	// swagger:operation POST /admin/users/{username}/keys admin adminCreatePublicKey
-	//
+	// ---
-	//     Consumes:
+	// summary: Add a public key on behalf of a user
+	// consumes:
 	// - application/json
-	//
+	// produces:
-	//     Produces:
 	// - application/json
-	//
+	// parameters:
-	//     Responses:
+	// - name: username
-	//       201: PublicKey
+	//   in: path
-	//       403: forbidden
+	//   description: username of the user
-	//       422: validationError
+	//   type: string
-	//       500: error
+	//   required: true
-
+	// responses:
+	//   "201":
+	//     "$ref": "#/responses/PublicKey"
+	//   "403":
+	//     "$ref": "#/responses/forbidden"
+	//   "422":
+	//     "$ref": "#/responses/validationError"
 	u := user.GetUserByParams(ctx)
 	if ctx.Written() {
 		return

routers/api/v1/api.go

@@ -4,11 +4,7 @@
 
 // Package v1 Gitea API.
 //
-// This provide API interface to communicate with this Gitea instance.
+// This documentation describes the Gitea API.
-//
-// Terms Of Service:
-//
-// there are no TOS at this moment, use at your own risk we take no responsibility
 //
 //     Schemes: http, https
 //     BasePath: /api/v1
@@ -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("/status", repo.GetCombinedCommitStatusByRef)
-					m.Get("/statuses", repo.GetCommitStatuses)
+					m.Get("/statuses", repo.GetCommitStatusesByRef)
 				})
 			}, repoAssignment())
 		})

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
+	// swagger:operation POST /markdown miscellaneous renderMarkdown
-	//
+	// ---
-	//     Consumes:
+	// summary: Render a markdown document as HTML
+	// parameters:
+	// - name: body
+	//   in: body
+	//   schema:
+	//     "$ref": "#/definitions/MarkdownOption"
+	// consumes:
 	// - application/json
-	//
+	// produces:
-	//     Produces:
 	//     - text/html
-	//
+	// responses:
-	//     Responses:
+	//   "200":
-	//       200: MarkdownRender
+	//     "$ref": "#/responses/MarkdownRender"
-	//       422: validationError
+	//   "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
+	// swagger:operation POST /markdown/raw miscellaneous renderMarkdownRaw
-	//
+	// ---
-	//     Consumes:
+	// summary: Render raw markdown as HTML
+	// parameters:
+	// - name: body
+	//   in: body
+	//   type: string
+	// consumes:
 	//     - text/plain
-	//
+	// produces:
-	//     Produces:
 	//     - text/html
-	//
+	// responses:
-	//     Responses:
+	//   "200":
-	//       200: MarkdownRender
+	//     "$ref": "#/responses/MarkdownRender"
-	//       422: validationError
+	//   "422":
+	//     "$ref": "#/responses/validationError"
 	body, err := ctx.Req.Body().Bytes()
 	if err != nil {
 		ctx.Error(422, "", err)

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
+	// swagger:operation GET /version miscellaneous getVersion
-	//
+	// ---
-	// Return Gitea running version.
+	// summary: Returns the version of the Gitea application
-	//
+	// produces:
-	// This show current running Gitea application version.
-	//
-	//     Produces:
 	// - application/json
-	//
+	// responses:
-	//     Responses:
+	//   "200":
-	//       200: ServerVersion
+	//     "$ref": "#/responses/ServerVersion"
-
 	ctx.JSON(200, &gitea.ServerVersion{Version: setting.AppVer})
 }

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
+	// swagger:operation GET /orgs/{org}/hooks organization orgListHooks
-	//
+	// ---
-	//     Produces:
+	// summary: List an organization's webhooks
+	// produces:
 	// - application/json
-	//
+	// responses:
-	//     Responses:
+	//   "200":
-	//       200: HookList
+	//     "$ref": "#/responses/HookList"
-	//       500: error
-
 	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
+	// swagger:operation GET /orgs/{org}/hooks/{id} organization orgGetHook
-	//
+	// ---
-	//     Produces:
+	// summary: Get a hook
+	// produces:
 	// - application/json
-	//
+	// responses:
-	//     Responses:
+	//   "200":
-	//       200: Hook
+	//     "$ref": "#/responses/Hook"
-	//       404: notFound
-	//       500: error
-
 	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
+	// swagger:operation POST /orgs/{org}/hooks/ organization orgCreateHook
-	//
+	// ---
-	//     Consumes:
+	// summary: Create a hook
+	// consumes:
 	// - application/json
-	//
+	// produces:
-	//     Produces:
 	// - application/json
-	//
+	// responses:
-	//     Responses:
+	//   "201":
-	//       201: Hook
+	//     "$ref": "#/responses/Hook"
-	//       422: validationError
-	//       500: error
-
 	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
+	// swagger:operation PATCH /orgs/{org}/hooks/{id} organization orgEditHook
-	//
+	// ---
-	//     Consumes:
+	// summary: Update a hook
+	// consumes:
 	// - application/json
-	//
+	// produces:
-	//     Produces:
 	// - application/json
-	//
+	// responses:
-	//     Responses:
+	//   "200":
-	//       200: Hook
+	//     "$ref": "#/responses/Hook"
-	//       422: validationError
-	//       404: notFound
-	//       500: error
-
 	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
+	// swagger:operation DELETE /orgs/{org}/hooks/{id} organization orgDeleteHook
-	//
+	// ---
-	//     Produces:
+	// summary: Delete a hook
+	// produces:
 	// - application/json
-	//
+	// responses:
-	//     Responses:
+	//   "204":
-	//       204: empty
+	//     "$ref": "#/responses/empty"
-	//       404: notFound
-	//       500: error
-
 	org := ctx.Org.Organization
 	hookID := ctx.ParamsInt64(":id")
 	if err := models.DeleteWebhookByOrgID(org.ID, hookID); err != nil {

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
+	// swagger:operation GET /orgs/{org}/members organization orgListMembers
-	//
+	// ---
-	//     Produces:
+	// summary: List an organization's members
+	// produces:
 	// - application/json
-	//
+	// parameters:
-	//     Responses:
+	// - name: org
-	//       200: UserList
+	//   in: path
-	//       500: error
+	//   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
+	// swagger:operation GET /orgs/{org}/public_members organization orgListPublicMembers
-	//
+	// ---
-	//     Produces:
+	// 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:
-	//     Responses:
+	//   "200":
-	//       200: UserList
+	//     "$ref": "#/responses/UserList"
-	//       500: error
-
 	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
+	// swagger:operation GET /orgs/{org}/members/{username} organization orgIsMember
-	//
+	// ---
-	//     Produces:
+	// summary: Check if a user is a member of an organization
-	//     - application/json
+	// parameters:
-	//
+	// - name: org
-	//     Responses:
+	//   in: path
-	//       204: empty
+	//   description: name of the organization
-	//       302: redirect
+	//   type: string
-	//       404: notFound
+	//   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
+	// swagger:operation GET /orgs/{org}/public_members/{username} organization orgIsPublicMember
-	//
+	// ---
-	//     Produces:
+	// summary: Check if a user is a public member of an organization
-	//     - application/json
+	// parameters:
-	//
+	// - name: org
-	//     Responses:
+	//   in: path
-	//       204: empty
+	//   description: name of the organization
-	//       404: notFound
+	//   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
+	// swagger:operation PUT /orgs/{org}/public_members/{username} organization orgPublicizeMember
-	//
+	// ---
-	//     Produces:
+	// summary: Publicize a user's membership
+	// produces:
 	// - application/json
-	//
+	// parameters:
-	//     Responses:
+	// - name: org
-	//       204: empty
+	//   in: path
-	//       403: forbidden
+	//   description: name of the organization
-	//       500: error
+	//   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
+	// swagger:operation DELETE /orgs/{org}/public_members/{username} organization orgConcealMember
-	//
+	// ---
-	//     Produces:
+	// summary: Conceal a user's membership
+	// produces:
 	// - application/json
-	//
+	// parameters:
-	//     Responses:
+	// - name: org
-	//       204: empty
+	//   in: path
-	//       403: forbidden
+	//   description: name of the organization
-	//       500: error
+	//   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
+	// swagger:operation DELETE /orgs/{org}/members/{username} organization orgDeleteMember
-	//
+	// ---
-	//     Produces:
+	// summary: Remove a member from an organization
+	// produces:
 	// - application/json
-	//
+	// parameters:
-	//     Responses:
+	// - name: org
-	//       204: empty
+	//   in: path
-	//       500: error
+	//   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

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

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

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)

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

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) {

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
+	// swagger:operation GET /repos/{owner}/{repo}/forks repository listForks
-	//
+	// ---
-	//     Produces:
+	// summary: List a repository's forks
+	// produces:
 	// - application/json
-	//
+	// parameters:
-	//     Responses:
+	// - name: owner
-	//       200: RepositoryList
+	//   in: path
-	//       500: error
+	//   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
+	// swagger:operation POST /repos/{owner}/{repo}/forks repository createFork
-	//
+	// ---
-	//     Produces:
+	// summary: Fork a repository
+	// produces:
 	// - application/json
-	//
+	// parameters:
-	//     Responses:
+	// - name: owner
-	//       202: Repository
+	//   in: path
-	//       403: forbidden
+	//   description: owner of the repo to fork
-	//       422: validationError
+	//   type: string
-	//       500: error
+	//   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 {

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
+	// swagger:operation GET /repos/{owner}/{repo}/hooks repository repoListHooks
-	//
+	// ---
-	//     Produces:
+	// summary: List the hooks in a repository
+	// produces:
 	// - application/json
-	//
+	// parameters:
-	//     Responses:
+	// - name: owner
-	//       200: HookList
+	//   in: path
-	//       500: error
+	//   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
+	// swagger:operation POST /repos/{owner}/{repo}/hooks repository repoCreateHook
-	//
+	// ---
-	//     Consumes:
+	// summary: Create a hook
+	// consumes:
 	// - application/json
-	//
+	// produces:
-	//     Produces:
 	// - application/json
-	//
+	// parameters:
-	//     Responses:
+	// - name: owner
-	//       200: Hook
+	//   in: path
-	//       422: validationError
+	//   description: owner of the repo
-	//       500: error
+	//   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
+	// swagger:operation PATCH /repos/{owner}/{repo}/hooks/{id} repository repoEditHook
-	//
+	// ---
-	//     Produces:
+	// summary: Edit a hook in a repository
+	// produces:
 	// - application/json
-	//
+	// parameters:
-	//     Responses:
+	// - name: owner
-	//       200: Hook
+	//   in: path
-	//       422: validationError
+	//   description: owner of the repo
-	//       500: error
+	//   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
+	// swagger:operation DELETE /repos/{user}/{repo}/hooks/{id} repository repoDeleteHook
-	//
+	// ---
-	//     Produces:
+	// summary: Delete a hook in a repository
+	// produces:
 	// - application/json
-	//
+	// parameters:
-	//     Responses:
+	// - name: owner
-	//       204: empty
+	//   in: path
-	//       404: notFound
+	//   description: owner of the repo
-	//       500: error
+	//   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)

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) {

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) {

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

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
+	// swagger:operation GET /repos/{owner}/{repo}/issues/{index}/times issue issueTrackedTimes
-	//
+	// ---
-	//     Produces:
+	// summary: List an issue's tracked times
+	// produces:
 	// - application/json
-	//
+	// parameters:
-	//     Responses:
+	// - name: owner
-	//       200: TrackedTimes
+	//   in: path
-	//	 404: error
+	//   description: owner of the repo
-	//       500: error
+	//   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
+	// swagger:operation Post /repos/{owner}/{repo}/issues/{index}/times issue issueAddTime
-	//
+	// ---
-	//     Produces:
+	// summary: Add a tracked time to a issue
+	// consumes:
 	// - application/json
-	//
+	// produces:
-	//     Responses:
+	// - application/json
-	//       200: TrackedTime
+	// parameters:
-	//       400: error
+	// - name: owner
-	//       403: error
+	//   in: path
-	//	 404: error
+	//   description: owner of the repo
-	//       500: error
+	//   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
+	// swagger:operation GET /repos/{owner}/{repo}/times/{tracker} user userTrackedTimes
-	//
+	// ---
-	//     Produces:
+	// summary: List a user's tracked times in a repo
+	// produces:
 	// - application/json
-	//
+	// parameters:
-	//     Responses:
+	// - name: owner
-	//       200: TrackedTimes
+	//   in: path
-	//       400: error
+	//   description: owner of the repo
-	//	 404: error
+	//   type: string
-	//       500: error
+	//   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
+	// swagger:operation GET /repos/{owner}/{repo}/times repository repoTrackedTimes
-	//
+	// ---
-	//     Produces:
+	// summary: List a repo's tracked times
+	// produces:
 	// - application/json
-	//
+	// parameters:
-	//     Responses:
+	// - name: owner
-	//       200: TrackedTimes
+	//   in: path
-	//       400: error
+	//   description: owner of the repo
-	//       500: error
+	//   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
+	// swagger:operation GET /user/times user userCurrentTrackedTimes
-	//
+	// ---
-	//     Produces:
+	// summary: List the current user's tracked times
+	// produces:
 	// - application/json
-	//
+	// responses:
-	//     Responses:
+	//   "200":
-	//       200: TrackedTimes
+	//     "$ref": "#/responses/TrackedTimeList"
-	//       500: error
 	trackedTimes, err := models.GetTrackedTimes(models.FindTrackedTimesOptions{UserID: ctx.User.ID})
 	if err != nil {
 		ctx.Error(500, "GetTrackedTimesByUser", err)

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")

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

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

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) {

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

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
+	// swagger:operation GET /repos/search repository repoSearch
-	//
+	// ---
-	//     Produces:
+	// summary: Search for repositories
+	// produces:
 	// - application/json
-	//
+	// parameters:
-	//     Responses:
+	// - name: q
-	//       200: SearchResults
+	//   in: query
-	//       422: validationError
+	//   description: keyword
-	//       500: SearchError
+	//   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
+	// swagger:operation POST /user/repos repository user createCurrentUserRepo
-	//
+	// ---
-	//     Consumes:
+	// summary: Create a repository
+	// consumes:
 	// - application/json
-	//
+	// produces:
-	//     Produces:
 	// - application/json
-	//
+	// parameters:
-	//     Responses:
+	// - name: body
-	//       201: Repository
+	//   in: body
-	//       403: forbidden
+	//   schema:
-	//       422: validationError
+	//     "$ref": "#/definitions/CreateRepoOption"
-	//       500: error
+	// responses:
-
+	//   "201":
-	// Shouldn't reach this condition, but just in case.
+	//     "$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
+	// swagger:operation POST /org/{org}/repos organization createOrgRepo
-	//
+	// ---
-	//     Consumes:
+	// summary: Create a repository in an organization
+	// consumes:
 	// - application/json
-	//
+	// produces:
-	//     Produces:
 	// - application/json
-	//
+	// parameters:
-	//     Responses:
+	// - name: org
-	//       201: Repository
+	//   in: path
-	//       422: validationError
+	//   description: name of organization
-	//       403: forbidden
+	//   type: string
-	//       500: error
+	//   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
+	// swagger:operation POST /repos/migrate repository repoMigrate
-	//
+	// ---
-	//     Consumes:
+	// summary: Migrate a remote git repository
+	// consumes:
 	// - application/json
-	//
+	// produces:
-	//     Produces:
 	// - application/json
-	//
+	// parameters:
-	//     Responses:
+	// - name: body
-	//       201: Repository
+	//   in: body
-	//       422: validationError
+	//   schema:
-	//       500: error
+	//     "$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
+	// swagger:operation GET /repos/{owner}/{repo} repository repoGet
-	//
+	// ---
-	//     Produces:
+	// summary: Get a repository
+	// produces:
 	// - application/json
-	//
+	// parameters:
-	//     Responses:
+	// - name: owner
-	//       200: Repository
+	//   in: path
-	//       500: error
+	//   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
+	// swagger:operation GET /repositories/{id} repository repoGetByID
-	//
+	// ---
-	//     Produces:
+	// summary: Get a repository by id
+	// produces:
 	// - application/json
-	//
+	// parameters:
-	//     Responses:
+	// - name: id
-	//       200: Repository
+	//   in: path
-	//       500: error
+	//   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
+	// swagger:operation DELETE /repos/{owner}/{repo} repository repoDelete
-	//
+	// ---
-	//     Produces:
+	// summary: Delete a repository
+	// produces:
 	// - application/json
-	//
+	// parameters:
-	//     Responses:
+	// - name: owner
-	//       204: empty
+	//   in: path
-	//       403: forbidden
+	//   description: owner of the repo to delete
-	//       500: error
+	//   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
+	// swagger:operation POST /repos/{owner}/{repo}/mirror-sync repository repoMirrorSync
-	//
+	// ---
-	//     Produces:
+	// summary: Sync a mirrored repository
+	// produces:
 	// - application/json
-	//
+	// parameters:
-	//     Responses:
+	// - name: owner
-	//       200: empty
+	//   in: path
-	//       403: forbidden
+	//   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() {

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)

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")
+	// swagger:operation GET /repos/{owner}/{repo}/statuses/{sha} repository repoListStatuses
-	if len(sha) == 0 {
+	// ---
-		sha = ctx.Params("ref")
+	// 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
+// GetCombinedCommitStatusByRef returns the combined status for any given commit hash
-func GetCombinedCommitStatus(ctx *context.APIContext) {
+func GetCombinedCommitStatusByRef(ctx *context.APIContext) {
-	sha := ctx.Params("sha")
+	// swagger:operation GET /repos/{owner}/{repo}/commits/{ref}/statuses repository repoGetCombinedStatusByRef
-	if len(sha) == 0 {
+	// ---
-		sha = ctx.Params("ref")
+	// 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

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)

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"`
+}

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"`
+}

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"`
+}

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
+}

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"`
+}

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"`
+}

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
+}

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
+	// swagger:operation GET /users/{username}/tokens user userGetTokens
-	//
+	// ---
-	//     Produces:
+	// summary: List the authenticated user's access tokens
+	// produces:
 	// - application/json
-	//
+	// responses:
-	//     Responses:
+	//   "200":
-	//       200: AccessTokenList
+	//     "$ref": "#/responses/AccessTokenList"
-	//       500: error
-
 	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
+	// swagger:operation POST /users/{username}/tokens user userCreateToken
-	//
+	// ---
-	//     Consumes:
+	// summary: Create an access token
+	// consumes:
 	// - application/json
-	//
+	// produces:
-	//     Produces:
 	// - application/json
-	//
+	// responses:
-	//     Responses:
+	//   "200":
-	//       200: AccessToken
+	//     "$ref": "#/responses/AccessToken"
-	//       500: error
-
 	t := &models.AccessToken{
 		UID:  ctx.User.ID,
 		Name: form.Name,

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
+// AddEmail add an email address
-// see https://github.com/gogits/go-gogs-client/wiki/Users-Emails#add-email-addresses
 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.DeleteEmailOption) {
-func DeleteEmail(ctx *context.APIContext, form api.CreateEmailOption) {
+	// 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

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
+	// swagger:operation GET /user/followers user userCurrentListFollowers
-	//
+	// ---
-	//     Produces:
+	// summary: List the authenticated user's followers
+	// produces:
 	// - application/json
-	//
+	// responses:
-	//     Responses:
+	//   "200":
-	//       200: UserList
+	//     "$ref": "#/responses/UserList"
-	//       500: error
-
 	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
+	// swagger:operation GET /users/{username}/followers user userListFollowers
-	//
+	// ---
-	//     Produces:
+	// summary: List the given user's followers
+	// produces:
 	// - application/json
-	//
+	// parameters:
-	//     Responses:
+	// - name: username
-	//       200: UserList
+	//   in: path
-	//       500: error
+	//   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
+	// swagger:operation GET /user/following user userCurrentListFollowing
-	//
+	// ---
-	//     Produces:
+	// summary: List the users that the authenticated user is following
+	// produces:
 	// - application/json
-	//
+	// responses:
-	//     Responses:
+	//   "200":
-	//       200: UserList
+	//     "$ref": "#/responses/UserList"
-	//       500: error
-
 	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
+	// swagger:operation GET /users/{username}/following user userListFollowing
-	//
+	// ---
-	//     Produces:
+	// summary: List the users that the given user is following
+	// produces:
 	// - application/json
-	//
+	// parameters:
-	//     Responses:
+	// - name: username
-	//       200: UserList
+	//   in: path
-	//       500: error
+	//   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
+	// swagger:operation GET /user/following/{followee} user userCurrentCheckFollowing
-	//
+	// ---
-	//     Responses:
+	// summary: Check whether a user is followed by the authenticated user
-	//       204: empty
+	// parameters:
-	//       404: notFound
+	// - 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
+	// swagger:operation GET /users/{follower}/following/{followee} user userCheckFollowing
-	//
+	// ---
-	//     Responses:
+	// summary: Check if one user is following another user
-	//       204: empty
+	// parameters:
-	//       404: notFound
+	// - 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
+	// swagger:operation PUT /user/following/{username} user userCurrentPutFollow
-	//
+	// ---
-	//     Responses:
+	// summary: Follow a user
-	//       204: empty
+	// parameters:
-	//       500: error
+	// - 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
+	// swagger:operation DELETE /user/following/{username} user userCurrentDeleteFollow
-	//
+	// ---
-	//     Responses:
+	// summary: Unfollow a user
-	//       204: empty
+	// parameters:
-	//       500: error
+	// - 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

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
+	// swagger:operation GET /users/{username}/gpg_keys user userListGPGKeys
-	//
+	// ---
-	//     Produces:
+	// summary: List the given user's GPG keys
+	// produces:
 	// - application/json
-	//
+	// parameters:
-	//     Responses:
+	// - name: username
-	//       200: GPGKeyList
+	//   in: path
-	//       500: error
+	//   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
+	// swagger:operation GET /user/gpg_keys user userCurrentListGPGKeys
-	//
+	// ---
-	//     Produces:
+	// summary: List the authenticated user's GPG keys
+	// produces:
 	// - application/json
-	//
+	// responses:
-	//     Responses:
+	//   "200":
-	//       200: GPGKeyList
+	//     "$ref": "#/responses/GPGKeyList"
-	//       500: error
-
 	listGPGKeys(ctx, ctx.User.ID)
 }
 
 //GetGPGKey get the GPG key based on a id
 func GetGPGKey(ctx *context.APIContext) {
-	// swagger:route GET /user/gpg_keys/{id} user userCurrentGetGPGKey
+	// swagger:operation GET /user/gpg_keys/{id} user userCurrentGetGPGKey
-	//
+	// ---
-	//     Produces:
+	// summary: Get a GPG key
+	// produces:
 	// - application/json
-	//
+	// parameters:
-	//     Responses:
+	// - name: id
-	//       200: GPGKey
+	//   in: path
-	//       404: notFound
+	//   description: id of key to get
-	//       500: error
+	//   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
+// swagger:parameters userCurrentPostGPGKey
-func CreateGPGKey(ctx *context.APIContext, form api.CreateGPGKeyOption) {
+type swaggerUserCurrentPostGPGKey struct {
-	// swagger:route POST /user/gpg_keys user userCurrentPostGPGKey
+	// in:body
-	//
+	Form api.CreateGPGKeyOption
-	//     Consumes:
+}
-	//     - application/json
-	//
-	//     Produces:
-	//     - application/json
-	//
-	//     Responses:
-	//       201: GPGKey
-	//       422: validationError
-	//       500: error
 
+//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
+	// swagger:operation DELETE /user/gpg_keys/{id} user userCurrentDeleteGPGKey
-	//
+	// ---
-	//     Produces:
+	// summary: Remove a GPG key
+	// produces:
 	// - application/json
-	//
+	// parameters:
-	//     Responses:
+	// - name: id
-	//       204: empty
+	//   in: path
-	//       403: forbidden
+	//   description: id of key to delete
-	//       500: error
+	//   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)
 	}

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
+	// swagger:operation GET /user/keys user userCurrentListKeys
-	//
+	// ---
-	//     Produces:
+	// summary: List the authenticated user's public keys
+	// produces:
 	// - application/json
-	//
+	// responses:
-	//     Responses:
+	//   "200":
-	//       200: PublicKeyList
+	//     "$ref": "#/responses/PublicKeyList"
-	//       500: error
-
 	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
+	// swagger:operation GET /users/{username}/keys user userListKeys
-	//
+	// ---
-	//     Produces:
+	// summary: List the given user's public keys
+	// produces:
 	// - application/json
-	//
+	// parameters:
-	//     Responses:
+	// - name: username
-	//       200: PublicKeyList
+	//   in: path
-	//       500: error
+	//   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
+	// swagger:operation GET /user/keys/{id} user userCurrentGetKey
-	//
+	// ---
-	//     Produces:
+	// summary: Get a public key
+	// produces:
 	// - application/json
-	//
+	// parameters:
-	//     Responses:
+	// - name: id
-	//       200: PublicKey
+	//   in: path
-	//       404: notFound
+	//   description: id of key to get
-	//       500: error
+	//   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
+	// swagger:operation POST /user/keys user userCurrentPostKey
-	//
+	// ---
-	//     Consumes:
+	// summary: Create a public key
+	// consumes:
 	// - application/json
-	//
+	// produces:
-	//     Produces:
 	// - application/json
-	//
+	// parameters:
-	//     Responses:
+	// - name: body
-	//       201: PublicKey
+	//   in: body
-	//       422: validationError
+	//   schema:
-	//       500: error
+	//     "$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
+	// swagger:operation DELETE /user/keys/{id} user userCurrentDeleteKey
-	//
+	// ---
-	//     Produces:
+	// summary: Delete a public key
+	// produces:
 	// - application/json
-	//
+	// parameters:
-	//     Responses:
+	// - name: id
-	//       204: empty
+	//   in: path
-	//       403: forbidden
+	//   description: id of key to delete
-	//       500: error
+	//   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")

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
+	// swagger:operation GET /users/{username}/repos user userListRepos
-	//
+	// ---
-	//     Produces:
+	// summary: List the repos owned by the given user
+	// produces:
 	// - application/json
-	//
+	// parameters:
-	//     Responses:
+	// - name: username
-	//       200: RepositoryList
+	//   in: path
-	//       500: error
+	//   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
+	// swagger:operation GET /user/repos user userCurrentListRepos
-	//
+	// ---
-	//     Produces:
+	// summary: List the repos that the authenticated user owns or has access to
+	// produces:
 	// - application/json
-	//
+	// responses:
-	//     Responses:
+	//   "200":
-	//       200: RepositoryList
+	//     "$ref": "#/responses/RepositoryList"
-	//       500: error
 	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
+	// swagger:operation GET /orgs/{org}/repos organization orgListRepos
-	//
+	// ---
-	//     Produces:
+	// summary: List an organization's repos
+	// produces:
 	// - application/json
-	//
+	// parameters:
-	//     Responses:
+	// - name: org
-	//       200: RepositoryList
+	//   in: path
-	//       500: error
+	//   description: name of the organization
-
+	//   type: string
+	//   required: true
+	// responses:
+	//   "200":
+	//     "$ref": "#/responses/RepositoryList"
 	listUserRepos(ctx, ctx.Org.Organization)
 }

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
+// GetStarredRepos returns the repos that the given user has starred
-// has starred
 func GetStarredRepos(ctx *context.APIContext) {
-	// swagger:route GET /users/{username}/starred user userListStarred
+	// swagger:operation GET /users/{username}/starred user userListStarred
-	//
+	// ---
-	//     Produces:
+	// summary: The repos that the given user has starred
+	// produces:
 	// - application/json
-	//
+	// parameters:
-	//     Responses:
+	// - name: username
-	//       200: RepositoryList
+	//   in: path
-	//       500: error
+	//   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
+	// swagger:operation GET /user/starred user userCurrentListStarred
-	//
+	// ---
-	//     Produces:
+	// summary: The repos that the authenticated user has starred
+	// produces:
 	// - application/json
-	//
+	// responses:
-	//     Responses:
+	//   "200":
-	//       200: RepositoryList
+	//     "$ref": "#/responses/RepositoryList"
-	//       500: error
-
 	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
+	// swagger:operation GET /user/starred/{owner}/{repo} user userCurrentCheckStarring
-	//
+	// ---
-	//     Responses:
+	// summary: Whether the authenticated is starring the repo
-	//       204: empty
+	// parameters:
-	//       404: notFound
+	// - 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
+	// swagger:operation PUT /user/starred/{owner}/{repo} user userCurrentPutStar
-	//
+	// ---
-	//     Responses:
+	// summary: Star the given repo
-	//       204: empty
+	// parameters:
-	//       500: error
+	// - 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
+	// swagger:operation DELETE /user/starred/{owner}/{repo} user userCurrentDeleteStar
-	//
+	// ---
-	//     Responses:
+	// summary: Unstar the given repo
-	//       204: empty
+	// parameters:
-	//       500: error
+	// - 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)

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
+	// swagger:operation GET /users/search user userSearch
-	//
+	// ---
-	//     Produces:
+	// summary: Search for users
+	// produces:
 	// - application/json
-	//
+	// parameters:
-	//     Responses:
+	// - name: q
-	//       200: UserList
+	//   in: query
-	//       500: error
+	//   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
+	// swagger:operation GET /users/{username} user userGet
-	//
+	// ---
-	//     Produces:
+	// summary: Get a user
+	// produces:
 	// - application/json
-	//
+	// parameters:
-	//     Responses:
+	// - name: username
-	//       200: User
+	//   in: path
-	//       404: notFound
+	//   description: username of user to get
-	//       500: error
+	//   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
+	// swagger:operation GET /user user userGetCurrent
-	//
+	// ---
-	//     Produces:
+	// summary: Get the authenticated user
+	// produces:
 	// - application/json
-	//
+	// responses:
-	//     Responses:
+	//   "200":
-	//       200: User
+	//     "$ref": "#/responses/User"
-
 	ctx.JSON(200, ctx.User.APIFormat())
 }

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
+	// swagger:operation GET /users/{username}/subscriptions user userListSubscriptions
-	//
+	// ---
-	//     Produces:
+	// summary: List the repositories watched by a user
+	// produces:
 	// - application/json
-	//
+	// parameters:
-	//     Responses:
+	// - name: username
-	//       200: RepositoryList
+	//   type: string
-	//       500: error
+	//   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
+	// swagger:operation GET /user/subscriptions user userCurrentListSubscriptions
-	//
+	// ---
-	//     Produces:
+	// summary: List repositories watched by the authenticated user
+	// produces:
 	// - application/json
-	//
+	// responses:
-	//     Responses:
+	//   "200":
-	//       200: RepositoryList
+	//     "$ref": "#/responses/RepositoryList"
-	//       500: error
-
 	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
+	// swagger:operation GET /repos/{owner}/{repo}/subscription repository userCurrentCheckSubscription
-	//
+	// ---
-	//     Responses:
+	// summary: Check if the current user is watching a repo
-	//       200: WatchInfo
+	// parameters:
-	//       404: notFound
+	// - 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
+	// swagger:operation PUT /repos/{owner}/{repo}/subscription repository userCurrentPutSubscription
-	//
+	// ---
-	//     Responses:
+	// summary: Watch a repo
-	//       200: WatchInfo
+	// parameters:
-	//       500: error
+	// - 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
+	// swagger:operation DELETE /repos/{owner}/{repo}/subscription repository userCurrentDeleteSubscription
-	//
+	// ---
-	//     Responses:
+	// summary: Unwatch a repo
-	//       204: empty
+	// parameters:
-	//       500: error
+	// - 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)

vendor/code.gitea.io/sdk/gitea/admin_user.go

@@ -11,21 +11,17 @@ import (
 )
 
 // CreateUserOption create user options
-// swagger:parameters adminCreateUser
 type CreateUserOption struct {
-	// in: body
 	SourceID int64 `json:"source_id"`
-	// in: body
 	LoginName string `json:"login_name"`
-	// in: body
+	// required: true
 	Username string `json:"username" binding:"Required;AlphaDashDot;MaxSize(35)"`
-	// in: body
 	FullName string `json:"full_name" binding:"MaxSize(100)"`
-	// in: body
+	// required: true
+	// swagger:strfmt email
 	Email string `json:"email" binding:"Required;Email;MaxSize(254)"`
-	// in: body
+	// required: true
-	Password string `json:"password" binding:"MaxSize(255)"`
+	Password string `json:"password" binding:"Required;MaxSize(255)"`
-	// in: body
 	SendNotify bool `json:"send_notify"`
 }
 
@@ -40,31 +36,20 @@ func (c *Client) AdminCreateUser(opt CreateUserOption) (*User, error) {
 }
 
 // EditUserOption edit user options
-// swagger:parameters adminEditUser
 type EditUserOption struct {
-	// in: body
 	SourceID int64 `json:"source_id"`
-	// in: body
 	LoginName string `json:"login_name"`
-	// in: body
 	FullName string `json:"full_name" binding:"MaxSize(100)"`
-	// in: body
+	// required: true
+	// swagger:strfmt email
 	Email string `json:"email" binding:"Required;Email;MaxSize(254)"`
-	// in: body
 	Password string `json:"password" binding:"MaxSize(255)"`
-	// in: body
 	Website string `json:"website" binding:"MaxSize(50)"`
-	// in: body
 	Location string `json:"location" binding:"MaxSize(50)"`
-	// in: body
 	Active *bool `json:"active"`
-	// in: body
 	Admin *bool `json:"admin"`
-	// in: body
 	AllowGitHook *bool `json:"allow_git_hook"`
-	// in: body
 	AllowImportLocal *bool `json:"allow_import_local"`
-	// in: body
 	MaxRepoCreation *int `json:"max_repo_creation"`
 }
 

vendor/code.gitea.io/sdk/gitea/attachment.go

@@ -0,0 +1,17 @@
+// 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 gitea // import "code.gitea.io/sdk/gitea"
+import "time"
+
+// Attachment a generic attachment
+type Attachment struct {
+	ID            int64     `json:"id"`
+	Name          string    `json:"name"`
+	Size          int64     `json:"size"`
+	DownloadCount int64     `json:"download_count"`
+	Created       time.Time `json:"created_at"`
+	UUID          string    `json:"uuid"`
+	DownloadURL   string    `json:"browser_download_url"`
+}

vendor/code.gitea.io/sdk/gitea/fork.go

@@ -20,9 +20,8 @@ func (c *Client) ListForks(user, repo string) ([]*Repository, error) {
 }
 
 // CreateForkOption options for creating a fork
-// swagger:parameters createFork
 type CreateForkOption struct {
-	// in: body
+	// organization name, if forking into an organization
 	Organization *string `json:"organization"`
 }
 

vendor/code.gitea.io/sdk/gitea/hook.go

@@ -20,7 +20,6 @@ var (
 )
 
 // Hook a hook is a web hook when one repository changed
-// swagger:response Hook
 type Hook struct {
 	ID      int64             `json:"id"`
 	Type    string            `json:"type"`
@@ -28,12 +27,13 @@ type Hook struct {
 	Config  map[string]string `json:"config"`
 	Events  []string          `json:"events"`
 	Active  bool              `json:"active"`
+	// swagger:strfmt date-time
 	Updated time.Time         `json:"updated_at"`
+	// swagger:strfmt date-time
 	Created time.Time         `json:"created_at"`
 }
 
 // HookList represents a list of API hook.
-// swagger:response HookList
 type HookList []*Hook
 
 // ListOrgHooks list all the hooks of one organization
@@ -61,15 +61,14 @@ func (c *Client) GetRepoHook(user, repo string, id int64) (*Hook, error) {
 }
 
 // CreateHookOption options when create a hook
-// swagger:parameters orgCreateHook repoCreateHook
 type CreateHookOption struct {
-	// in: body
+	// required: true
+	// enum: gitea,gogs,slack,discord
 	Type string `json:"type" binding:"Required"`
-	// in: body
+	// required: true
 	Config map[string]string `json:"config" binding:"Required"`
-	// in: body
 	Events []string `json:"events"`
-	// in: body
+	// default: false
 	Active bool `json:"active"`
 }
 
@@ -94,13 +93,9 @@ func (c *Client) CreateRepoHook(user, repo string, opt CreateHookOption) (*Hook,
 }
 
 // EditHookOption options when modify one hook
-// swagger:parameters orgEditHook repoEditHook
 type EditHookOption struct {
-	// in: body
 	Config map[string]string `json:"config"`
-	// in: body
 	Events []string `json:"events"`
-	// in: body
 	Active *bool `json:"active"`
 }
 
@@ -142,25 +137,32 @@ type Payloader interface {
 	JSONPayload() ([]byte, error)
 }
 
-// PayloadUser FIXME
+// PayloadUser represents the author or committer of a commit
 type PayloadUser struct {
+	// Full name of the commit author
 	Name     string `json:"name"`
+	// swagger:strfmt email
 	Email    string `json:"email"`
 	UserName string `json:"username"`
 }
 
-// PayloadCommit FIXME: consider use same format as API when commits API are added.
+// FIXME: consider using same format as API when commits API are added.
+//        applies to PayloadCommit and PayloadCommitVerification
+
+// PayloadCommit represents a commit
 type PayloadCommit struct {
+	// sha1 hash of the commit
 	ID           string                     `json:"id"`
 	Message      string                     `json:"message"`
 	URL          string                     `json:"url"`
 	Author       *PayloadUser               `json:"author"`
 	Committer    *PayloadUser               `json:"committer"`
 	Verification *PayloadCommitVerification `json:"verification"`
+	// swagger:strfmt date-time
 	Timestamp    time.Time                  `json:"timestamp"`
 }
 
-// PayloadCommitVerification represent the GPG verification part of a commit. FIXME: like PayloadCommit consider use same format as API when commits API are added.
+// PayloadCommitVerification represents the GPG verification of a commit
 type PayloadCommitVerification struct {
 	Verified  bool   `json:"verified"`
 	Reason    string `json:"reason"`

vendor/code.gitea.io/sdk/gitea/issue.go

@@ -27,7 +27,8 @@ type PullRequestMeta struct {
 	Merged    *time.Time `json:"merged_at"`
 }
 
-// Issue an issue to a repository
+// Issue represents an issue in a repository
+// swagger:model
 type Issue struct {
 	ID        int64      `json:"id"`
 	URL       string     `json:"url"`
@@ -38,9 +39,15 @@ type Issue struct {
 	Labels    []*Label   `json:"labels"`
 	Milestone *Milestone `json:"milestone"`
 	Assignee  *User      `json:"assignee"`
+	// Whether the issue is open or closed
+	//
+	// type: string
+	// enum: open,closed
 	State     StateType  `json:"state"`
 	Comments  int        `json:"comments"`
+	// swagger:strfmt date-time
 	Created   time.Time  `json:"created_at"`
+	// swagger:strfmt date-time
 	Updated   time.Time  `json:"updated_at"`
 
 	PullRequest *PullRequestMeta `json:"pull_request"`
@@ -78,10 +85,14 @@ func (c *Client) GetIssue(owner, repo string, index int64) (*Issue, error) {
 
 // CreateIssueOption options to create one issue
 type CreateIssueOption struct {
+	// required:true
 	Title     string  `json:"title" binding:"Required"`
 	Body      string  `json:"body"`
+	// username of assignee
 	Assignee  string  `json:"assignee"`
+	// milestone id
 	Milestone int64   `json:"milestone"`
+	// list of label ids
 	Labels    []int64 `json:"labels"`
 	Closed    bool    `json:"closed"`
 }
@@ -97,7 +108,7 @@ func (c *Client) CreateIssue(owner, repo string, opt CreateIssueOption) (*Issue,
 		jsonHeader, bytes.NewReader(body), issue)
 }
 
-// EditIssueOption edit issue options
+// EditIssueOption options for editing an issue
 type EditIssueOption struct {
 	Title     string  `json:"title"`
 	Body      *string `json:"body"`

vendor/code.gitea.io/sdk/gitea/issue_comment.go

@@ -11,7 +11,7 @@ import (
 	"time"
 )
 
-// Comment represents a comment in commit and issue page.
+// Comment represents a comment on a commit or issue
 type Comment struct {
 	ID       int64     `json:"id"`
 	HTMLURL  string    `json:"html_url"`
@@ -19,7 +19,9 @@ type Comment struct {
 	IssueURL string    `json:"issue_url"`
 	Poster   *User     `json:"user"`
 	Body     string    `json:"body"`
+	// swagger:strfmt date-time
 	Created  time.Time `json:"created_at"`
+	// swagger:strfmt date-time
 	Updated  time.Time `json:"updated_at"`
 }
 
@@ -35,8 +37,9 @@ func (c *Client) ListRepoIssueComments(owner, repo string) ([]*Comment, error) {
 	return comments, c.getParsedResponse("GET", fmt.Sprintf("/repos/%s/%s/issues/comments", owner, repo), nil, nil, &comments)
 }
 
-// CreateIssueCommentOption is option when creating an issue comment.
+// CreateIssueCommentOption options for creating a comment on an issue
 type CreateIssueCommentOption struct {
+	// required:true
 	Body string `json:"body" binding:"Required"`
 }
 
@@ -50,8 +53,9 @@ func (c *Client) CreateIssueComment(owner, repo string, index int64, opt CreateI
 	return comment, c.getParsedResponse("POST", fmt.Sprintf("/repos/%s/%s/issues/%d/comments", owner, repo, index), jsonHeader, bytes.NewReader(body), comment)
 }
 
-// EditIssueCommentOption is option when editing an issue comment.
+// EditIssueCommentOption options for editing a comment
 type EditIssueCommentOption struct {
+	// required: true
 	Body string `json:"body" binding:"Required"`
 }
 

vendor/code.gitea.io/sdk/gitea/issue_label.go

@@ -11,14 +11,16 @@ import (
 )
 
 // Label a label to an issue or a pr
+// swagger:model
 type Label struct {
 	ID    int64  `json:"id"`
 	Name  string `json:"name"`
+	// example: 00aabb
 	Color string `json:"color"`
 	URL   string `json:"url"`
 }
 
-// ListRepoLabels list lables of one reppsitory
+// ListRepoLabels list labels of one repository
 func (c *Client) ListRepoLabels(owner, repo string) ([]*Label, error) {
 	labels := make([]*Label, 0, 10)
 	return labels, c.getParsedResponse("GET", fmt.Sprintf("/repos/%s/%s/labels", owner, repo), nil, nil, &labels)
@@ -31,9 +33,12 @@ func (c *Client) GetRepoLabel(owner, repo string, id int64) (*Label, error) {
 	return label, c.getParsedResponse("GET", fmt.Sprintf("/repos/%s/%s/labels/%d", owner, repo, id), nil, nil, label)
 }
 
-// CreateLabelOption create options when one label of repository
+// CreateLabelOption options for creating a label
 type CreateLabelOption struct {
+	// required:true
 	Name  string `json:"name" binding:"Required"`
+	// required:true
+	// example: #00aabb
 	Color string `json:"color" binding:"Required;Size(7)"`
 }
 
@@ -48,7 +53,7 @@ func (c *Client) CreateLabel(owner, repo string, opt CreateLabelOption) (*Label,
 		jsonHeader, bytes.NewReader(body), label)
 }
 
-// EditLabelOption edit label options
+// EditLabelOption options for editing a label
 type EditLabelOption struct {
 	Name  *string `json:"name"`
 	Color *string `json:"color"`
@@ -71,8 +76,9 @@ func (c *Client) DeleteLabel(owner, repo string, id int64) error {
 	return err
 }
 
-// IssueLabelsOption list one issue's labels options
+// IssueLabelsOption a collection of labels
 type IssueLabelsOption struct {
+	// list of label IDs
 	Labels []int64 `json:"labels"`
 }
 

vendor/code.gitea.io/sdk/gitea/issue_milestone.go

@@ -19,7 +19,9 @@ type Milestone struct {
 	State        StateType  `json:"state"`
 	OpenIssues   int        `json:"open_issues"`
 	ClosedIssues int        `json:"closed_issues"`
+	// swagger:strfmt date-time
 	Closed       *time.Time `json:"closed_at"`
+	// swagger:strfmt date-time
 	Deadline     *time.Time `json:"due_on"`
 }
 
@@ -35,10 +37,11 @@ func (c *Client) GetMilestone(owner, repo string, id int64) (*Milestone, error)
 	return milestone, c.getParsedResponse("GET", fmt.Sprintf("/repos/%s/%s/milestones/%d", owner, repo, id), nil, nil, milestone)
 }
 
-// CreateMilestoneOption options when creating milestone
+// CreateMilestoneOption options for creating a milestone
 type CreateMilestoneOption struct {
 	Title       string     `json:"title"`
 	Description string     `json:"description"`
+	// swagger:strfmt date-time
 	Deadline    *time.Time `json:"due_on"`
 }
 
@@ -52,7 +55,7 @@ func (c *Client) CreateMilestone(owner, repo string, opt CreateMilestoneOption)
 	return milestone, c.getParsedResponse("POST", fmt.Sprintf("/repos/%s/%s/milestones", owner, repo), jsonHeader, bytes.NewReader(body), milestone)
 }
 
-// EditMilestoneOption options when modify milestone
+// EditMilestoneOption options for editing a milestone
 type EditMilestoneOption struct {
 	Title       string     `json:"title"`
 	Description *string    `json:"description"`

vendor/code.gitea.io/sdk/gitea/issue_tracked_time.go

@@ -12,9 +12,9 @@ import (
 )
 
 // TrackedTime worked time for an issue / pr
-// swagger:response TrackedTime
 type TrackedTime struct {
 	ID      int64     `json:"id"`
+	// swagger:strfmt date-time
 	Created time.Time `json:"created"`
 	// Time in seconds
 	Time    int64 `json:"time"`
@@ -23,7 +23,6 @@ type TrackedTime struct {
 }
 
 // TrackedTimes represent a list of tracked times
-// swagger:response TrackedTimes
 type TrackedTimes []*TrackedTime
 
 // GetUserTrackedTimes list tracked times of a user
@@ -44,10 +43,10 @@ func (c *Client) GetMyTrackedTimes() (TrackedTimes, error) {
 	return times, c.getParsedResponse("GET", "/user/times", nil, nil, &times)
 }
 
-// AddTimeOption adds time manually to an issue
+// AddTimeOption options for adding time to an issue
-// swagger:parameters addTime
 type AddTimeOption struct {
-	// in: body
+	// time in seconds
+	// required: true
 	Time int64 `json:"time" binding:"Required"`
 }
 

vendor/code.gitea.io/sdk/gitea/miscellaneous.go

@@ -4,22 +4,19 @@
 
 package gitea
 
-// SearchResults results of search
+// SearchResults results of a successful search
-// swagger:response SearchResults
 type SearchResults struct {
 	OK   bool          `json:"ok"`
 	Data []*Repository `json:"data"`
 }
 
-// SearchError error of failing search
+// SearchError error of a failed search
-// swagger:response SearchError
 type SearchError struct {
 	OK    bool   `json:"ok"`
 	Error string `json:"error"`
 }
 
 // MarkdownOption markdown options
-// swagger:parameters renderMarkdown
 type MarkdownOption struct {
 	// Text markdown to render
 	//
@@ -44,9 +41,8 @@ type MarkdownOption struct {
 type MarkdownRender string
 
 // ServerVersion wraps the version of the server
-// swagger:response ServerVersion
 type ServerVersion struct {
-	Version string
+	Version string `json:"version"`
 }
 
 // ServerVersion returns the version of the server

vendor/code.gitea.io/sdk/gitea/org.go

@@ -10,8 +10,7 @@ import (
 	"fmt"
 )
 
-// Organization a group of some repositories, users and teams
+// Organization represents an organization
-// swagger:response Organization
 type Organization struct {
 	ID          int64  `json:"id"`
 	UserName    string `json:"username"`
@@ -40,22 +39,17 @@ func (c *Client) GetOrg(orgname string) (*Organization, error) {
 	return org, c.getParsedResponse("GET", fmt.Sprintf("/orgs/%s", orgname), nil, nil, org)
 }
 
-// CreateOrgOption create one organization options
+// CreateOrgOption options for creating an organization
-// swagger:parameters adminCreateOrg
 type CreateOrgOption struct {
-	// in: body
+	// required: true
 	UserName string `json:"username" binding:"Required"`
-	// in: body
 	FullName string `json:"full_name"`
-	// in: body
 	Description string `json:"description"`
-	// in: body
 	Website string `json:"website"`
-	// in: body
 	Location string `json:"location"`
 }
 
-// EditOrgOption edit one organization options
+// EditOrgOption options for editing an organization
 type EditOrgOption struct {
 	FullName    string `json:"full_name"`
 	Description string `json:"description"`

vendor/code.gitea.io/sdk/gitea/org_team.go

@@ -4,24 +4,29 @@
 
 package gitea
 
-// Team is a sub virtual organization of one Organization
+// Team represents a team in an organization
 type Team struct {
 	ID          int64  `json:"id"`
 	Name        string `json:"name"`
 	Description string `json:"description"`
+	// enum: none,read,write,admin,owner
 	Permission  string `json:"permission"`
 }
 
-// CreateTeamOption options when create team
+// CreateTeamOption options for creating a team
 type CreateTeamOption struct {
+	// required: true
 	Name        string `json:"name" binding:"Required;AlphaDashDot;MaxSize(30)"`
 	Description string `json:"description" binding:"MaxSize(255)"`
+	// enum: read,write,admin
 	Permission  string `json:"permission"`
 }
 
-// EditTeamOption options when edit team
+// EditTeamOption options for editing a team
 type EditTeamOption struct {
+	// required: true
 	Name        string `json:"name" binding:"Required;AlphaDashDot;MaxSize(30)"`
 	Description string `json:"description" binding:"MaxSize(255)"`
+	// enum: read,write,admin
 	Permission  string `json:"permission"`
 }

vendor/code.gitea.io/sdk/gitea/pull.go

@@ -11,7 +11,7 @@ import (
 	"time"
 )
 
-// PullRequest represents a pull request API object.
+// PullRequest represents a pull request
 type PullRequest struct {
 	ID        int64      `json:"id"`
 	URL       string     `json:"url"`
@@ -31,6 +31,7 @@ type PullRequest struct {
 
 	Mergeable      bool       `json:"mergeable"`
 	HasMerged      bool       `json:"merged"`
+	// swagger:strfmt date-time
 	Merged         *time.Time `json:"merged_at"`
 	MergedCommitID *string    `json:"merge_commit_sha"`
 	MergedBy       *User      `json:"merged_by"`
@@ -39,11 +40,13 @@ type PullRequest struct {
 	Head      *PRBranchInfo `json:"head"`
 	MergeBase string        `json:"merge_base"`
 
+	// swagger:strfmt date-time
 	Created *time.Time `json:"created_at"`
+	// swagger:strfmt date-time
 	Updated *time.Time `json:"updated_at"`
 }
 
-// PRBranchInfo base branch info when send a PR
+// PRBranchInfo information about a branch
 type PRBranchInfo struct {
 	Name       string      `json:"label"`
 	Ref        string      `json:"ref"`
@@ -52,7 +55,7 @@ type PRBranchInfo struct {
 	Repository *Repository `json:"repo"`
 }
 
-// ListPullRequestsOptions options when list PRs
+// ListPullRequestsOptions options for listing pull requests
 type ListPullRequestsOptions struct {
 	Page  int    `json:"page"`
 	State string `json:"state"`

vendor/code.gitea.io/sdk/gitea/release.go

@@ -23,7 +23,9 @@ type Release struct {
 	ZipURL       string    `json:"zipball_url"`
 	IsDraft      bool      `json:"draft"`
 	IsPrerelease bool      `json:"prerelease"`
+	// swagger:strfmt date-time
 	CreatedAt    time.Time `json:"created_at"`
+	// swagger:strfmt date-time
 	PublishedAt  time.Time `json:"published_at"`
 	Publisher    *User     `json:"author"`
 }
@@ -48,6 +50,7 @@ func (c *Client) GetRelease(user, repo string, id int64) (*Release, error) {
 
 // CreateReleaseOption options when creating a release
 type CreateReleaseOption struct {
+	// required: true
 	TagName      string `json:"tag_name" binding:"Required"`
 	Target       string `json:"target_commitish"`
 	Title        string `json:"name"`

vendor/code.gitea.io/sdk/gitea/repo.go

@@ -11,15 +11,14 @@ import (
 	"time"
 )
 
-// Permission represents a API permission.
+// Permission represents a set of permissions
 type Permission struct {
 	Admin bool `json:"admin"`
 	Push  bool `json:"push"`
 	Pull  bool `json:"pull"`
 }
 
-// Repository represents a API repository.
+// Repository represents a repository
-// swagger:response Repository
 type Repository struct {
 	ID            int64       `json:"id"`
 	Owner         *User       `json:"owner"`
@@ -41,15 +40,13 @@ type Repository struct {
 	Watchers      int         `json:"watchers_count"`
 	OpenIssues    int         `json:"open_issues_count"`
 	DefaultBranch string      `json:"default_branch"`
+	// swagger:strfmt date-time
 	Created       time.Time   `json:"created_at"`
+	// swagger:strfmt date-time
 	Updated       time.Time   `json:"updated_at"`
 	Permissions   *Permission `json:"permissions,omitempty"`
 }
 
-// RepositoryList represents a list of API repository.
-// swagger:response RepositoryList
-type RepositoryList []*Repository
-
 // ListMyRepos lists all repositories for the authenticated user that has access to.
 func (c *Client) ListMyRepos() ([]*Repository, error) {
 	repos := make([]*Repository, 0, 10)
@@ -69,36 +66,24 @@ func (c *Client) ListOrgRepos(org string) ([]*Repository, error) {
 }
 
 // CreateRepoOption options when creating repository
-//swagger:parameters createOrgRepo adminCreateRepo createCurrentUserRepo
+// swagger:model
 type CreateRepoOption struct {
 	// Name of the repository to create
 	//
-	// in: body
+	// required: true
 	// unique: true
 	Name string `json:"name" binding:"Required;AlphaDashDot;MaxSize(100)"`
 	// Description of the repository to create
-	//
-	// in: body
 	Description string `json:"description" binding:"MaxSize(255)"`
-	// Is the repository to create private ?
+	// Whether the repository is private
-	//
-	// in: body
 	Private bool `json:"private"`
-	// Init the repository to create ?
+	// Whether the repository should be auto-intialized?
-	//
-	// in: body
 	AutoInit bool `json:"auto_init"`
 	// Gitignores to use
-	//
-	// in: body
 	Gitignores string `json:"gitignores"`
 	// License to use
-	//
-	// in: body
 	License string `json:"license"`
 	// Readme of the repository to create
-	//
-	// in: body
 	Readme string `json:"readme"`
 }
 
@@ -134,24 +119,18 @@ func (c *Client) DeleteRepo(owner, repo string) error {
 	return err
 }
 
-// MigrateRepoOption options when migrate repository from an external place
+// MigrateRepoOption options for migrating a repository from an external service
-// swagger:parameters repoMigrate
 type MigrateRepoOption struct {
-	// in: body
+	// required: true
 	CloneAddr string `json:"clone_addr" binding:"Required"`
-	// in: body
 	AuthUsername string `json:"auth_username"`
-	// in: body
 	AuthPassword string `json:"auth_password"`
-	// in: body
+	// required: true
 	UID int `json:"uid" binding:"Required"`
-	// in: body
+	// required: true
 	RepoName string `json:"repo_name" binding:"Required"`
-	// in: body
 	Mirror bool `json:"mirror"`
-	// in: body
 	Private bool `json:"private"`
-	// in: body
 	Description string `json:"description"`
 }
 

vendor/code.gitea.io/sdk/gitea/repo_branch.go

@@ -8,7 +8,7 @@ import (
 	"fmt"
 )
 
-// Branch represents a repository branch.
+// Branch represents a repository branch
 type Branch struct {
 	Name   string         `json:"name"`
 	Commit *PayloadCommit `json:"commit"`

vendor/code.gitea.io/sdk/gitea/repo_collaborator.go

@@ -33,7 +33,7 @@ func (c *Client) IsCollaborator(user, repo, collaborator string) (bool, error) {
 	return false, nil
 }
 
-// AddCollaboratorOption options when add some user as a collaborator of a repository
+// AddCollaboratorOption options when adding a user as a collaborator of a repository
 type AddCollaboratorOption struct {
 	Permission *string `json:"permission"`
 }

vendor/code.gitea.io/sdk/gitea/repo_key.go

@@ -17,6 +17,7 @@ type DeployKey struct {
 	Key      string    `json:"key"`
 	URL      string    `json:"url"`
 	Title    string    `json:"title"`
+	// swagger:strfmt date-time
 	Created  time.Time `json:"created_at"`
 	ReadOnly bool      `json:"read_only"`
 }
@@ -33,18 +34,15 @@ func (c *Client) GetDeployKey(user, repo string, keyID int64) (*DeployKey, error
 	return key, c.getParsedResponse("GET", fmt.Sprintf("/repos/%s/%s/keys/%d", user, repo, keyID), nil, nil, &key)
 }
 
-// CreateKeyOption options when create deploy key
+// CreateKeyOption options when creating a key
-// swagger:parameters userCurrentPostKey adminCreatePublicKey
 type CreateKeyOption struct {
 	// Title of the key to add
 	//
-	// in: body
 	// required: true
 	// unique: true
 	Title string `json:"title" binding:"Required"`
 	// An armored SSH key to add
 	//
-	// in: body
 	// required: true
 	// unique: true
 	Key string `json:"key" binding:"Required"`

vendor/code.gitea.io/sdk/gitea/repo_watch.go

@@ -10,8 +10,7 @@ import (
 	"time"
 )
 
-// WatchInfo represents a API watch status of one repository
+// WatchInfo represents an API watch status of one repository
-// swagger:response WatchInfo
 type WatchInfo struct {
 	Subscribed    bool        `json:"subscribed"`
 	Ignored       bool        `json:"ignored"`

vendor/code.gitea.io/sdk/gitea/status.go

@@ -37,7 +37,9 @@ type Status struct {
 	URL         string      `json:"url"`
 	Context     string      `json:"context"`
 	Creator     *User       `json:"creator"`
+	// swagger:strfmt date-time
 	Created     time.Time   `json:"created_at"`
+	// swagger:strfmt date-time
 	Updated     time.Time   `json:"updated_at"`
 }
 

vendor/code.gitea.io/sdk/gitea/user.go

@@ -9,20 +9,21 @@ import (
 	"fmt"
 )
 
-// User represents a API user.
+// User represents a user
-// swagger:response User
+// swagger:model
 type User struct {
+	// the user's id
 	ID        int64  `json:"id"`
+	// the user's username
 	UserName  string `json:"login"`
+	// the user's full name
 	FullName  string `json:"full_name"`
+	// swagger:strfmt email
 	Email     string `json:"email"`
+	// URL to the user's avatar
 	AvatarURL string `json:"avatar_url"`
 }
 
-// UserList represents a list of API user.
-// swagger:response UserList
-type UserList []*User
-
 // MarshalJSON implements the json.Marshaler interface for User, adding field(s) for backward compatibility
 func (u User) MarshalJSON() ([]byte, error) {
 	// Re-declaring User to avoid recursion

vendor/code.gitea.io/sdk/gitea/user_email.go

@@ -9,8 +9,9 @@ import (
 	"encoding/json"
 )
 
-// Email en email information of user
+// Email an email address belonging to a user
 type Email struct {
+	// swagger:strfmt email
 	Email    string `json:"email"`
 	Verified bool   `json:"verified"`
 	Primary  bool   `json:"primary"`
@@ -22,8 +23,9 @@ func (c *Client) ListEmails() ([]*Email, error) {
 	return emails, c.getParsedResponse("GET", "/user/emails", nil, nil, &emails)
 }
 
-// CreateEmailOption options when create an email
+// CreateEmailOption options when creating email addresses
 type CreateEmailOption struct {
+	// email addresses to add
 	Emails []string `json:"emails"`
 }
 
@@ -37,8 +39,14 @@ func (c *Client) AddEmail(opt CreateEmailOption) ([]*Email, error) {
 	return emails, c.getParsedResponse("POST", "/user/emails", jsonHeader, bytes.NewReader(body), emails)
 }
 
+// DeleteEmailOption options when deleting email addresses
+type DeleteEmailOption struct {
+	// email addresses to delete
+	Emails []string `json:"emails"`
+}
+
 // DeleteEmail delete one email of current users'
-func (c *Client) DeleteEmail(opt CreateEmailOption) error {
+func (c *Client) DeleteEmail(opt DeleteEmailOption) error {
 	body, err := json.Marshal(&opt)
 	if err != nil {
 		return err

vendor/code.gitea.io/sdk/gitea/user_gpgkey.go

@@ -11,12 +11,7 @@ import (
 	"time"
 )
 
-// GPGKeyList represents a list of GPGKey
-// swagger:response GPGKeyList
-type GPGKeyList []*GPGKey
-
 // GPGKey a user GPG key to sign commit and tag in repository
-// swagger:response GPGKey
 type GPGKey struct {
 	ID                int64          `json:"id"`
 	PrimaryKeyID      string         `json:"primary_key_id"`
@@ -28,7 +23,9 @@ type GPGKey struct {
 	CanEncryptComms   bool           `json:"can_encrypt_comms"`
 	CanEncryptStorage bool           `json:"can_encrypt_storage"`
 	CanCertify        bool           `json:"can_certify"`
+	// swagger:strfmt date-time
 	Created           time.Time      `json:"created_at,omitempty"`
+	// swagger:strfmt date-time
 	Expires           time.Time      `json:"expires_at,omitempty"`
 }
 
@@ -40,11 +37,9 @@ type GPGKeyEmail struct {
 }
 
 // CreateGPGKeyOption options create user GPG key
-// swagger:parameters userCurrentPostGPGKey
 type CreateGPGKeyOption struct {
 	// An armored GPG key to add
 	//
-	// in: body
 	// required: true
 	// unique: true
 	ArmoredKey string `json:"armored_public_key" binding:"Required"`

vendor/code.gitea.io/sdk/gitea/user_key.go

@@ -11,17 +11,13 @@ import (
 	"time"
 )
 
-// PublicKeyList represents a list of PublicKey
-// swagger:response PublicKeyList
-type PublicKeyList []*PublicKey
-
 // PublicKey publickey is a user key to push code to repository
-// swagger:response PublicKey
 type PublicKey struct {
 	ID      int64     `json:"id"`
 	Key     string    `json:"key"`
 	URL     string    `json:"url,omitempty"`
 	Title   string    `json:"title,omitempty"`
+	// swagger:strfmt date-time
 	Created time.Time `json:"created_at,omitempty"`
 }
 

vendor/vendor.json

@@ -9,10 +9,10 @@
 			"revisionTime": "2017-10-23T00:52:09Z"
 		},
 		{
-			"checksumSHA1": "Zgp5RqU+20L2p9TNl1rSsUIWEEE=",
+			"checksumSHA1": "OICEgmUefW4L4l/FK/NVFnl/aOM=",
 			"path": "code.gitea.io/sdk/gitea",
-			"revision": "bc243ad6c268d60658c71185452334b300c268cf",
+			"revision": "1da52cf95ff3e7953227cfa0469e1c05a7d02557",
-			"revisionTime": "2017-08-21T08:23:17Z"
+			"revisionTime": "2017-11-12T09:10:33Z"
 		},
 		{
 			"checksumSHA1": "bOODD4Gbw3GfcuQPU2dI40crxxk=",