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

1 files changed, 135 insertions, 66 deletions

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