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

4 files changed, 432 insertions, 126 deletions

diff --git a/routers/api/v1/org/hook.go b/routers/api/v1/org/hook.go
index d8a4c45fc8..0a77d795e6 100644
--- a/routers/api/v1/org/hook.go
+++ b/routers/api/v1/org/hook.go
@@ -15,15 +15,14 @@ import (
 
 // ListHooks list an organziation's webhooks
 func ListHooks(ctx *context.APIContext) {
-	// swagger:route GET /orgs/{orgname}/hooks organization orgListHooks
-	//
-	//     Produces:
-	//     - application/json
-	//
-	//     Responses:
-	//       200: HookList
-	//       500: error
-
+	// swagger:operation GET /orgs/{org}/hooks organization orgListHooks
+	// ---
+	// summary: List an organization's webhooks
+	// produces:
+	// - application/json
+	// responses:
+	//   "200":
+	//     "$ref": "#/responses/HookList"
 	org := ctx.Org.Organization
 	orgHooks, err := models.GetWebhooksByOrgID(org.ID)
 	if err != nil {
@@ -39,16 +38,14 @@ func ListHooks(ctx *context.APIContext) {
 
 // GetHook get an organization's hook by id
 func GetHook(ctx *context.APIContext) {
-	// swagger:route GET /orgs/{orgname}/hooks/{id} organization orgGetHook
-	//
-	//     Produces:
-	//     - application/json
-	//
-	//     Responses:
-	//       200: Hook
-	//       404: notFound
-	//       500: error
-
+	// swagger:operation GET /orgs/{org}/hooks/{id} organization orgGetHook
+	// ---
+	// summary: Get a hook
+	// produces:
+	// - application/json
+	// responses:
+	//   "200":
+	//     "$ref": "#/responses/Hook"
 	org := ctx.Org.Organization
 	hookID := ctx.ParamsInt64(":id")
 	hook, err := utils.GetOrgHook(ctx, org.ID, hookID)
@@ -60,19 +57,16 @@ func GetHook(ctx *context.APIContext) {
 
 // CreateHook create a hook for an organization
 func CreateHook(ctx *context.APIContext, form api.CreateHookOption) {
-	// swagger:route POST /orgs/{orgname}/hooks/ organization orgCreateHook
-	//
-	//     Consumes:
-	//     - application/json
-	//
-	//     Produces:
-	//     - application/json
-	//
-	//     Responses:
-	//       201: Hook
-	//       422: validationError
-	//       500: error
-
+	// swagger:operation POST /orgs/{org}/hooks/ organization orgCreateHook
+	// ---
+	// summary: Create a hook
+	// consumes:
+	// - application/json
+	// produces:
+	// - application/json
+	// responses:
+	//   "201":
+	//     "$ref": "#/responses/Hook"
 	if !utils.CheckCreateHookOption(ctx, &form) {
 		return
 	}
@@ -81,36 +75,30 @@ func CreateHook(ctx *context.APIContext, form api.CreateHookOption) {
 
 // EditHook modify a hook of a repository
 func EditHook(ctx *context.APIContext, form api.EditHookOption) {
-	// swagger:route PATCH /orgs/{orgname}/hooks/{id} organization orgEditHook
-	//
-	//     Consumes:
-	//     - application/json
-	//
-	//     Produces:
-	//     - application/json
-	//
-	//     Responses:
-	//       200: Hook
-	//       422: validationError
-	//       404: notFound
-	//       500: error
-
+	// swagger:operation PATCH /orgs/{org}/hooks/{id} organization orgEditHook
+	// ---
+	// summary: Update a hook
+	// consumes:
+	// - application/json
+	// produces:
+	// - application/json
+	// responses:
+	//   "200":
+	//     "$ref": "#/responses/Hook"
 	hookID := ctx.ParamsInt64(":id")
 	utils.EditOrgHook(ctx, &form, hookID)
 }
 
 // DeleteHook delete a hook of an organization
 func DeleteHook(ctx *context.APIContext) {
-	// swagger:route DELETE /orgs/{orgname}/hooks/{id} organization orgDeleteHook
-	//
-	//     Produces:
-	//     - application/json
-	//
-	//     Responses:
-	//       204: empty
-	//       404: notFound
-	//       500: error
-
+	// swagger:operation DELETE /orgs/{org}/hooks/{id} organization orgDeleteHook
+	// ---
+	// summary: Delete a hook
+	// produces:
+	// - application/json
+	// responses:
+	//   "204":
+	//     "$ref": "#/responses/empty"
 	org := ctx.Org.Organization
 	hookID := ctx.ParamsInt64(":id")
 	if err := models.DeleteWebhookByOrgID(org.ID, hookID); err != nil {
diff --git a/routers/api/v1/org/member.go b/routers/api/v1/org/member.go
index 3495370556..7cae7c19fa 100644
--- a/routers/api/v1/org/member.go
+++ b/routers/api/v1/org/member.go
@@ -53,45 +53,68 @@ func listMembers(ctx *context.APIContext, publicOnly bool) {
 
 // ListMembers list an organization's members
 func ListMembers(ctx *context.APIContext) {
-	// swagger:route GET /orgs/{orgname}/members organization orgListMembers
-	//
-	//     Produces:
-	//     - application/json
-	//
-	//     Responses:
-	//       200: UserList
-	//       500: error
-
+	// swagger:operation GET /orgs/{org}/members organization orgListMembers
+	// ---
+	// summary: List an organization's members
+	// produces:
+	// - application/json
+	// parameters:
+	// - name: org
+	//   in: path
+	//   description: name of the organization
+	//   type: string
+	//   required: true
+	// responses:
+	//   "200":
+	//     "$ref": "#/responses/UserList"
 	publicOnly := ctx.User == nil || !ctx.Org.Organization.IsOrgMember(ctx.User.ID)
 	listMembers(ctx, publicOnly)
 }
 
 // ListPublicMembers list an organization's public members
 func ListPublicMembers(ctx *context.APIContext) {
-	// swagger:route GET /orgs/{orgname}/public_members organization orgListPublicMembers
-	//
-	//     Produces:
-	//     - application/json
-	//
-	//     Responses:
-	//       200: UserList
-	//       500: error
-
+	// swagger:operation GET /orgs/{org}/public_members organization orgListPublicMembers
+	// ---
+	// summary: List an organization's public members
+	// parameters:
+	// - name: org
+	//   in: path
+	//   description: name of the organization
+	//   type: string
+	//   required: true
+	// produces:
+	// - application/json
+	// responses:
+	//   "200":
+	//     "$ref": "#/responses/UserList"
 	listMembers(ctx, true)
 }
 
 // IsMember check if a user is a member of an organization
 func IsMember(ctx *context.APIContext) {
-	// swagger:route GET /orgs/{orgname}/members/{username} organization orgIsMember
-	//
-	//     Produces:
-	//     - application/json
-	//
-	//     Responses:
-	//       204: empty
-	//       302: redirect
-	//       404: notFound
-
+	// swagger:operation GET /orgs/{org}/members/{username} organization orgIsMember
+	// ---
+	// summary: Check if a user is a member of an organization
+	// parameters:
+	// - name: org
+	//   in: path
+	//   description: name of the organization
+	//   type: string
+	//   required: true
+	// - name: username
+	//   in: path
+	//   description: username of the user
+	//   type: string
+	//   required: true
+	// responses:
+	//   "204":
+	//     description: user is a member
+	//     schema:
+	//       "$ref": "#/responses/empty"
+	//   "404":
+	//     description: user is not a member
+	//     schema:
+	//       "$ref": "#/responses/empty"
 	userToCheck := user.GetUserByParams(ctx)
 	if ctx.Written() {
 		return
@@ -113,15 +136,29 @@ func IsMember(ctx *context.APIContext) {
 
 // IsPublicMember check if a user is a public member of an organization
 func IsPublicMember(ctx *context.APIContext) {
-	// swagger:route GET /orgs/{orgname}/public_members/{username} organization orgIsPublicMember
-	//
-	//     Produces:
-	//     - application/json
-	//
-	//     Responses:
-	//       204: empty
-	//       404: notFound
-
+	// swagger:operation GET /orgs/{org}/public_members/{username} organization orgIsPublicMember
+	// ---
+	// summary: Check if a user is a public member of an organization
+	// parameters:
+	// - name: org
+	//   in: path
+	//   description: name of the organization
+	//   type: string
+	//   required: true
+	// - name: username
+	//   in: path
+	//   description: username of the user
+	//   type: string
+	//   required: true
+	// responses:
+	//   "204":
+	//     description: user is a public member
+	//     schema:
+	//       "$ref": "#/responses/empty"
+	//   "404":
+	//     description: user is not a public member
+	//     schema:
+	//       "$ref": "#/responses/empty"
 	userToCheck := user.GetUserByParams(ctx)
 	if ctx.Written() {
 		return
@@ -135,16 +172,27 @@ func IsPublicMember(ctx *context.APIContext) {
 
 // PublicizeMember make a member's membership public
 func PublicizeMember(ctx *context.APIContext) {
-	// swagger:route PUT /orgs/{orgname}/public_members/{username} organization orgPublicizeMember
-	//
-	//     Produces:
-	//     - application/json
-	//
-	//     Responses:
-	//       204: empty
-	//       403: forbidden
-	//       500: error
-
+	// swagger:operation PUT /orgs/{org}/public_members/{username} organization orgPublicizeMember
+	// ---
+	// summary: Publicize a user's membership
+	// produces:
+	// - application/json
+	// parameters:
+	// - name: org
+	//   in: path
+	//   description: name of the organization
+	//   type: string
+	//   required: true
+	// - name: username
+	//   in: path
+	//   description: username of the user
+	//   type: string
+	//   required: true
+	// responses:
+	//   "204":
+	//     description: membership publicized
+	//     schema:
+	//       "$ref": "#/responses/empty"
 	userToPublicize := user.GetUserByParams(ctx)
 	if ctx.Written() {
 		return
@@ -163,16 +211,25 @@ func PublicizeMember(ctx *context.APIContext) {
 
 // ConcealMember make a member's membership not public
 func ConcealMember(ctx *context.APIContext) {
-	// swagger:route DELETE /orgs/{orgname}/public_members/{username} organization orgConcealMember
-	//
-	//     Produces:
-	//     - application/json
-	//
-	//     Responses:
-	//       204: empty
-	//       403: forbidden
-	//       500: error
-
+	// swagger:operation DELETE /orgs/{org}/public_members/{username} organization orgConcealMember
+	// ---
+	// summary: Conceal a user's membership
+	// produces:
+	// - application/json
+	// parameters:
+	// - name: org
+	//   in: path
+	//   description: name of the organization
+	//   type: string
+	//   required: true
+	// - name: username
+	//   in: path
+	//   description: username of the user
+	//   type: string
+	//   required: true
+	// responses:
+	//   "204":
+	//     "$ref": "#/responses/empty"
 	userToConceal := user.GetUserByParams(ctx)
 	if ctx.Written() {
 		return
@@ -191,15 +248,27 @@ func ConcealMember(ctx *context.APIContext) {
 
 // DeleteMember remove a member from an organization
 func DeleteMember(ctx *context.APIContext) {
-	// swagger:route DELETE /orgs/{orgname}/members/{username} organization orgDeleteMember
-	//
-	//     Produces:
-	//     - application/json
-	//
-	//     Responses:
-	//       204: empty
-	//       500: error
-
+	// swagger:operation DELETE /orgs/{org}/members/{username} organization orgDeleteMember
+	// ---
+	// summary: Remove a member from an organization
+	// produces:
+	// - application/json
+	// parameters:
+	// - name: org
+	//   in: path
+	//   description: name of the organization
+	//   type: string
+	//   required: true
+	// - name: username
+	//   in: path
+	//   description: username of the user
+	//   type: string
+	//   required: true
+	// responses:
+	//   "204":
+	//     description: member removed
+	//     schema:
+	//       "$ref": "#/responses/empty"
 	member := user.GetUserByParams(ctx)
 	if ctx.Written() {
 		return
diff --git a/routers/api/v1/org/org.go b/routers/api/v1/org/org.go
index ec55b9ebe4..c24a4aeb10 100644
--- a/routers/api/v1/org/org.go
+++ b/routers/api/v1/org/org.go
@@ -27,14 +27,33 @@ func listUserOrgs(ctx *context.APIContext, u *models.User, all bool) {
 }
 
 // ListMyOrgs list all my orgs
-// see https://github.com/gogits/go-gogs-client/wiki/Organizations#list-your-organizations
 func ListMyOrgs(ctx *context.APIContext) {
+	// swagger:operation GET /user/orgs organization orgListCurrentUserOrgs
+	// ---
+	// summary: List the current user's organizations
+	// produces:
+	// - application/json
+	// responses:
+	//   "200":
+	//     "$ref": "#/responses/OrganizationList"
 	listUserOrgs(ctx, ctx.User, true)
 }
 
 // ListUserOrgs list user's orgs
-// see https://github.com/gogits/go-gogs-client/wiki/Organizations#list-user-organizations
 func ListUserOrgs(ctx *context.APIContext) {
+	// swagger:operation GET /user/{username}/orgs organization orgListUserOrgs
+	// ---
+	// summary: List a user's organizations
+	// produces:
+	// - application/json
+	// parameters:
+	// - name: username
+	//   in: path
+	//   description: username of user
+	//   type: string
+	// responses:
+	//   "200":
+	//     "$ref": "#/responses/OrganizationList"
 	u := user.GetUserByParams(ctx)
 	if ctx.Written() {
 		return
@@ -43,14 +62,46 @@ func ListUserOrgs(ctx *context.APIContext) {
 }
 
 // Get get an organization
-// see https://github.com/gogits/go-gogs-client/wiki/Organizations#get-an-organization
 func Get(ctx *context.APIContext) {
+	// swagger:operation GET /orgs/{org} organization orgGet
+	// ---
+	// summary: Get an organization
+	// produces:
+	// - application/json
+	// parameters:
+	// - name: org
+	//   in: path
+	//   description: name of the organization to get
+	//   type: string
+	//   required: true
+	// responses:
+	//   "200":
+	//     "$ref": "#/responses/Organization"
 	ctx.JSON(200, convert.ToOrganization(ctx.Org.Organization))
 }
 
 // Edit change an organization's information
-// see https://github.com/gogits/go-gogs-client/wiki/Organizations#edit-an-organization
 func Edit(ctx *context.APIContext, form api.EditOrgOption) {
+	// swagger:operation PATCH /orgs/{org} organization orgEdit
+	// ---
+	// summary: Edit an organization
+	// consumes:
+	// - application/json
+	// produces:
+	// - application/json
+	// parameters:
+	// - name: org
+	//   in: path
+	//   description: name of the organization to edit
+	//   type: string
+	//   required: true
+	// - name: body
+	//   in: body
+	//   schema:
+	//     "$ref": "#/definitions/EditOrgOption"
+	// responses:
+	//   "200":
+	//     "$ref": "#/responses/Organization"
 	org := ctx.Org.Organization
 	org.FullName = form.FullName
 	org.Description = form.Description
diff --git a/routers/api/v1/org/team.go b/routers/api/v1/org/team.go
index dbd6ccc460..eead7dd8fd 100644
--- a/routers/api/v1/org/team.go
+++ b/routers/api/v1/org/team.go
@@ -15,6 +15,20 @@ import (
 
 // ListTeams list all the teams of an organization
 func ListTeams(ctx *context.APIContext) {
+	// swagger:operation GET /orgs/{org}/teams organization orgListTeams
+	// ---
+	// summary: List an organization's teams
+	// produces:
+	// - application/json
+	// parameters:
+	// - name: org
+	//   in: path
+	//   description: name of the organization
+	//   type: string
+	//   required: true
+	// responses:
+	//   "200":
+	//     "$ref": "#/responses/TeamList"
 	org := ctx.Org.Organization
 	if err := org.GetTeams(); err != nil {
 		ctx.Error(500, "GetTeams", err)
@@ -30,11 +44,45 @@ func ListTeams(ctx *context.APIContext) {
 
 // GetTeam api for get a team
 func GetTeam(ctx *context.APIContext) {
+	// swagger:operation GET /teams/{id} organization orgGetTeam
+	// ---
+	// summary: Get a team
+	// produces:
+	// - application/json
+	// parameters:
+	// - name: id
+	//   in: path
+	//   description: id of the team to get
+	//   type: integer
+	//   required: true
+	// responses:
+	//   "200":
+	//     "$ref": "#/responses/Team"
 	ctx.JSON(200, convert.ToTeam(ctx.Org.Team))
 }
 
 // CreateTeam api for create a team
 func CreateTeam(ctx *context.APIContext, form api.CreateTeamOption) {
+	// swagger:operation POST /orgs/{org}/teams organization orgCreateTeam
+	// ---
+	// summary: Create a team
+	// consumes:
+	// - application/json
+	// produces:
+	// - application/json
+	// parameters:
+	// - name: org
+	//   in: path
+	//   description: name of the organization
+	//   type: string
+	//   required: true
+	// - name: body
+	//   in: body
+	//   schema:
+	//     "$ref": "#/definitions/CreateTeamOption"
+	// responses:
+	//   "201":
+	//     "$ref": "#/responses/Team"
 	team := &models.Team{
 		OrgID:       ctx.Org.Organization.ID,
 		Name:        form.Name,
@@ -55,6 +103,26 @@ func CreateTeam(ctx *context.APIContext, form api.CreateTeamOption) {
 
 // EditTeam api for edit a team
 func EditTeam(ctx *context.APIContext, form api.EditTeamOption) {
+	// swagger:operation PATCH /teams/{id} organization orgEditTeam
+	// ---
+	// summary: Edit a team
+	// consumes:
+	// - application/json
+	// produces:
+	// - application/json
+	// parameters:
+	// - name: id
+	//   in: path
+	//   description: id of the team to edit
+	//   type: integer
+	//   required: true
+	// - name: body
+	//   in: body
+	//   schema:
+	//     "$ref": "#/definitions/EditTeamOption"
+	// responses:
+	//   "200":
+	//     "$ref": "#/responses/Team"
 	team := &models.Team{
 		ID:          ctx.Org.Team.ID,
 		OrgID:       ctx.Org.Team.OrgID,
@@ -71,6 +139,20 @@ func EditTeam(ctx *context.APIContext, form api.EditTeamOption) {
 
 // DeleteTeam api for delete a team
 func DeleteTeam(ctx *context.APIContext) {
+	// swagger:operation DELETE /teams/{id} organization orgDeleteTeam
+	// ---
+	// summary: Delete a team
+	// parameters:
+	// - name: id
+	//   in: path
+	//   description: id of the team to delete
+	//   type: integer
+	//   required: true
+	// responses:
+	//   "204":
+	//     description: team deleted
+	//     schema:
+	//       "$ref": "#/responses/empty"
 	if err := models.DeleteTeam(ctx.Org.Team); err != nil {
 		ctx.Error(500, "DeleteTeam", err)
 		return
@@ -80,6 +162,20 @@ func DeleteTeam(ctx *context.APIContext) {
 
 // GetTeamMembers api for get a team's members
 func GetTeamMembers(ctx *context.APIContext) {
+	// swagger:operation GET /teams/{id}/members organization orgListTeamMembers
+	// ---
+	// summary: List a team's members
+	// produces:
+	// - application/json
+	// parameters:
+	// - name: id
+	//   in: path
+	//   description: id of the team
+	//   type: integer
+	//   required: true
+	// responses:
+	//   "200":
+	//     "$ref": "#/responses/UserList"
 	if !models.IsOrganizationMember(ctx.Org.Team.OrgID, ctx.User.ID) {
 		ctx.Status(404)
 		return
@@ -98,6 +194,25 @@ func GetTeamMembers(ctx *context.APIContext) {
 
 // AddTeamMember api for add a member to a team
 func AddTeamMember(ctx *context.APIContext) {
+	// swagger:operation PUT /teams/{id}/members/{username} organization orgAddTeamMember
+	// ---
+	// summary: Add a team member
+	// produces:
+	// - application/json
+	// parameters:
+	// - name: id
+	//   in: path
+	//   description: id of the team
+	//   type: integer
+	//   required: true
+	// - name: username
+	//   in: path
+	//   description: username of the user to add
+	//   type: string
+	//   required: true
+	// responses:
+	//   "204":
+	//     "$ref": "#/responses/empty"
 	u := user.GetUserByParams(ctx)
 	if ctx.Written() {
 		return
@@ -111,6 +226,25 @@ func AddTeamMember(ctx *context.APIContext) {
 
 // RemoveTeamMember api for remove one member from a team
 func RemoveTeamMember(ctx *context.APIContext) {
+	// swagger:operation DELETE /teams/{id}/members/{username} organization orgAddTeamMember
+	// ---
+	// summary: Remove a team member
+	// produces:
+	// - application/json
+	// parameters:
+	// - name: id
+	//   in: path
+	//   description: id of the team
+	//   type: integer
+	//   required: true
+	// - name: username
+	//   in: path
+	//   description: username of the user to remove
+	//   type: string
+	//   required: true
+	// responses:
+	//   "204":
+	//     "$ref": "#/responses/empty"
 	u := user.GetUserByParams(ctx)
 	if ctx.Written() {
 		return
@@ -125,6 +259,20 @@ func RemoveTeamMember(ctx *context.APIContext) {
 
 // GetTeamRepos api for get a team's repos
 func GetTeamRepos(ctx *context.APIContext) {
+	// swagger:operation GET /teams/{id}/repos organization orgListTeamRepos
+	// ---
+	// summary: List a team's repos
+	// produces:
+	// - application/json
+	// parameters:
+	// - name: id
+	//   in: path
+	//   description: id of the team
+	//   type: integer
+	//   required: true
+	// responses:
+	//   "200":
+	//     "$ref": "#/responses/RepositoryList"
 	team := ctx.Org.Team
 	if err := team.GetRepositories(); err != nil {
 		ctx.Error(500, "GetTeamRepos", err)
@@ -157,6 +305,30 @@ func getRepositoryByParams(ctx *context.APIContext) *models.Repository {
 
 // AddTeamRepository api for adding a repository to a team
 func AddTeamRepository(ctx *context.APIContext) {
+	// swagger:operation PUT /teams/{id}/repos/{org}/{repo} organization orgAddTeamMember
+	// ---
+	// summary: Add a repository to a team
+	// produces:
+	// - application/json
+	// parameters:
+	// - name: id
+	//   in: path
+	//   description: id of the team
+	//   type: integer
+	//   required: true
+	// - name: org
+	//   in: path
+	//   description: organization that owns the repo to add
+	//   type: string
+	//   required: true
+	// - name: repo
+	//   in: path
+	//   description: name of the repo to add
+	//   type: string
+	//   required: true
+	// responses:
+	//   "204":
+	//     "$ref": "#/responses/empty"
 	repo := getRepositoryByParams(ctx)
 	if ctx.Written() {
 		return
@@ -177,6 +349,32 @@ func AddTeamRepository(ctx *context.APIContext) {
 
 // RemoveTeamRepository api for removing a repository from a team
 func RemoveTeamRepository(ctx *context.APIContext) {
+	// swagger:operation DELETE /teams/{id}/repos/{org}/{repo} organization orgAddTeamMember
+	// ---
+	// summary: Remove a repository from a team
+	// description: This does not delete the repository, it only removes the
+	//              repository from the team.
+	// produces:
+	// - application/json
+	// parameters:
+	// - name: id
+	//   in: path
+	//   description: id of the team
+	//   type: integer
+	//   required: true
+	// - name: org
+	//   in: path
+	//   description: organization that owns the repo to remove
+	//   type: string
+	//   required: true
+	// - name: repo
+	//   in: path
+	//   description: name of the repo to remove
+	//   type: string
+	//   required: true
+	// responses:
+	//   "204":
+	//     "$ref": "#/responses/empty"
 	repo := getRepositoryByParams(ctx)
 	if ctx.Written() {
 		return