Improve swagger doc (#2274)

* Add swagger comment for adminCreateOrg

* Add swagger comment for admin route

* add hook swagger doc

* Add tags

* Add auth

* Fix name of responses

* Edit name method

* Update vendor

* make generate-swagger

2 files changed, 122 insertions, 0 deletions

diff --git a/routers/api/v1/org/hook.go b/routers/api/v1/org/hook.go
index 3a0b74ac21..d8a4c45fc8 100644
--- a/routers/api/v1/org/hook.go
+++ b/routers/api/v1/org/hook.go
@@ -15,6 +15,15 @@ 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
+
 	org := ctx.Org.Organization
 	orgHooks, err := models.GetWebhooksByOrgID(org.ID)
 	if err != nil {
@@ -30,6 +39,16 @@ 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
+
 	org := ctx.Org.Organization
 	hookID := ctx.ParamsInt64(":id")
 	hook, err := utils.GetOrgHook(ctx, org.ID, hookID)
@@ -41,6 +60,19 @@ 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
+
 	if !utils.CheckCreateHookOption(ctx, &form) {
 		return
 	}
@@ -49,12 +81,36 @@ 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
+
 	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
+
 	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 476025e644..3495370556 100644
--- a/routers/api/v1/org/member.go
+++ b/routers/api/v1/org/member.go
@@ -53,17 +53,45 @@ 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
+
 	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
+
 	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
+
 	userToCheck := user.GetUserByParams(ctx)
 	if ctx.Written() {
 		return
@@ -85,6 +113,15 @@ 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
+
 	userToCheck := user.GetUserByParams(ctx)
 	if ctx.Written() {
 		return
@@ -98,6 +135,16 @@ 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
+
 	userToPublicize := user.GetUserByParams(ctx)
 	if ctx.Written() {
 		return
@@ -116,6 +163,16 @@ 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
+
 	userToConceal := user.GetUserByParams(ctx)
 	if ctx.Written() {
 		return
@@ -134,6 +191,15 @@ 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
+
 	member := user.GetUserByParams(ctx)
 	if ctx.Written() {
 		return