Fix swagger errors (#4220)

Fix all the resting errors to have a valid swagger file.

They are still some warnings but nothing blocking.

Doing so I found that some request still misses son parameters for some POST/PUT/PATCH request. This means the a client generated from the swagger file will not work completely. 

Fix #4088 by activating validation in drone
Should fix #4010.

13 files changed, 158 insertions, 51 deletions

diff --git a/routers/api/v1/misc/markdown.go b/routers/api/v1/misc/markdown.go
index fd7d1489b3..633dff98eb 100644
--- a/routers/api/v1/misc/markdown.go
+++ b/routers/api/v1/misc/markdown.go
@@ -62,9 +62,12 @@ func MarkdownRaw(ctx *context.APIContext) {
 	// ---
 	// summary: Render raw markdown as HTML
 	// parameters:
-	// - name: body
-	//   in: body
-	//   type: string
+	//     - name: body
+	//       in: body
+	//       description: Request body to render
+	//       required: true
+	//       schema:
+	//         type: string
 	// consumes:
 	//     - text/plain
 	// produces:
diff --git a/routers/api/v1/org/hook.go b/routers/api/v1/org/hook.go
index 0a77d795e6..83d2a5e5ba 100644
--- a/routers/api/v1/org/hook.go
+++ b/routers/api/v1/org/hook.go
@@ -20,6 +20,12 @@ func ListHooks(ctx *context.APIContext) {
 	// summary: List an organization's webhooks
 	// produces:
 	// - application/json
+	// parameters:
+	// - name: org
+	//   in: path
+	//   description: name of the organization
+	//   type: string
+	//   required: true
 	// responses:
 	//   "200":
 	//     "$ref": "#/responses/HookList"
@@ -43,6 +49,17 @@ func GetHook(ctx *context.APIContext) {
 	// summary: Get a hook
 	// produces:
 	// - application/json
+	// parameters:
+	// - name: org
+	//   in: path
+	//   description: name of the organization
+	//   type: string
+	//   required: true
+	// - name: id
+	//   in: path
+	//   description: id of the hook to get
+	//   type: integer
+	//   required: true
 	// responses:
 	//   "200":
 	//     "$ref": "#/responses/Hook"
@@ -64,9 +81,17 @@ func CreateHook(ctx *context.APIContext, form api.CreateHookOption) {
 	// - application/json
 	// produces:
 	// - application/json
+	// parameters:
+	// - name: org
+	//   in: path
+	//   description: name of the organization
+	//   type: string
+	//   required: true
 	// responses:
 	//   "201":
 	//     "$ref": "#/responses/Hook"
+
+	//TODO in body params
 	if !utils.CheckCreateHookOption(ctx, &form) {
 		return
 	}
@@ -82,9 +107,22 @@ func EditHook(ctx *context.APIContext, form api.EditHookOption) {
 	// - application/json
 	// produces:
 	// - application/json
+	// parameters:
+	// - name: org
+	//   in: path
+	//   description: name of the organization
+	//   type: string
+	//   required: true
+	// - name: id
+	//   in: path
+	//   description: id of the hook to update
+	//   type: integer
+	//   required: true
 	// responses:
 	//   "200":
 	//     "$ref": "#/responses/Hook"
+
+	//TODO in body params
 	hookID := ctx.ParamsInt64(":id")
 	utils.EditOrgHook(ctx, &form, hookID)
 }
@@ -96,6 +134,17 @@ func DeleteHook(ctx *context.APIContext) {
 	// summary: Delete a hook
 	// produces:
 	// - application/json
+	// parameters:
+	// - name: org
+	//   in: path
+	//   description: name of the organization
+	//   type: string
+	//   required: true
+	// - name: id
+	//   in: path
+	//   description: id of the hook to delete
+	//   type: integer
+	//   required: true
 	// responses:
 	//   "204":
 	//     "$ref": "#/responses/empty"
diff --git a/routers/api/v1/org/team.go b/routers/api/v1/org/team.go
index 408d8921db..b8dd026bf3 100644
--- a/routers/api/v1/org/team.go
+++ b/routers/api/v1/org/team.go
@@ -227,7 +227,7 @@ 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
+	// swagger:operation DELETE /teams/{id}/members/{username} organization orgRemoveTeamMember
 	// ---
 	// summary: Remove a team member
 	// produces:
@@ -306,7 +306,7 @@ 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
+	// swagger:operation PUT /teams/{id}/repos/{org}/{repo} organization orgAddTeamRepository
 	// ---
 	// summary: Add a repository to a team
 	// produces:
@@ -350,7 +350,7 @@ 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
+	// swagger:operation DELETE /teams/{id}/repos/{org}/{repo} organization orgRemoveTeamRepository
 	// ---
 	// summary: Remove a repository from a team
 	// description: This does not delete the repository, it only removes the
diff --git a/routers/api/v1/repo/file.go b/routers/api/v1/repo/file.go
index a3c8309ac5..610247bc27 100644
--- a/routers/api/v1/repo/file.go
+++ b/routers/api/v1/repo/file.go
@@ -64,7 +64,7 @@ func GetRawFile(ctx *context.APIContext) {
 
 // GetArchive get archive of a repository
 func GetArchive(ctx *context.APIContext) {
-	// swagger:operation GET /repos/{owner}/{repo}/archive/{filepath} repository repoGetArchive
+	// swagger:operation GET /repos/{owner}/{repo}/archive/{archive} repository repoGetArchive
 	// ---
 	// summary: Get an archive of a repository
 	// produces:
diff --git a/routers/api/v1/repo/hook.go b/routers/api/v1/repo/hook.go
index e412a7f1f2..1f121dfc38 100644
--- a/routers/api/v1/repo/hook.go
+++ b/routers/api/v1/repo/hook.go
@@ -189,6 +189,11 @@ func EditHook(ctx *context.APIContext, form api.EditHookOption) {
 	//   description: name of the repo
 	//   type: string
 	//   required: true
+	// - name: id
+	//   in: path
+	//   description: index of the hook
+	//   type: integer
+	//   required: true
 	// - name: body
 	//   in: body
 	//   schema:
@@ -202,7 +207,7 @@ func EditHook(ctx *context.APIContext, form api.EditHookOption) {
 
 // DeleteHook delete a hook of a repository
 func DeleteHook(ctx *context.APIContext) {
-	// swagger:operation DELETE /repos/{user}/{repo}/hooks/{id} repository repoDeleteHook
+	// swagger:operation DELETE /repos/{owner}/{repo}/hooks/{id} repository repoDeleteHook
 	// ---
 	// summary: Delete a hook in a repository
 	// produces:
diff --git a/routers/api/v1/repo/issue_comment.go b/routers/api/v1/repo/issue_comment.go
index 2865ea9165..0cbf6493d3 100644
--- a/routers/api/v1/repo/issue_comment.go
+++ b/routers/api/v1/repo/issue_comment.go
@@ -31,7 +31,7 @@ func ListIssueComments(ctx *context.APIContext) {
 	//   description: name of the repo
 	//   type: string
 	//   required: true
-	// - name: id
+	// - name: index
 	//   in: path
 	//   description: index of the issue
 	//   type: integer
@@ -139,7 +139,7 @@ func CreateIssueComment(ctx *context.APIContext, form api.CreateIssueCommentOpti
 	//   description: name of the repo
 	//   type: string
 	//   required: true
-	// - name: id
+	// - name: index
 	//   in: path
 	//   description: index of the issue
 	//   type: integer
diff --git a/routers/api/v1/repo/issue_tracked_time.go b/routers/api/v1/repo/issue_tracked_time.go
index 1111d672a7..9be9fee91a 100644
--- a/routers/api/v1/repo/issue_tracked_time.go
+++ b/routers/api/v1/repo/issue_tracked_time.go
@@ -21,7 +21,7 @@ func trackedTimesToAPIFormat(trackedTimes []*models.TrackedTime) []*api.TrackedT
 
 // ListTrackedTimes list all the tracked times of an issue
 func ListTrackedTimes(ctx *context.APIContext) {
-	// swagger:operation GET /repos/{owner}/{repo}/issues/{index}/times issue issueTrackedTimes
+	// swagger:operation GET /repos/{owner}/{repo}/issues/{id}/times issue issueTrackedTimes
 	// ---
 	// summary: List an issue's tracked times
 	// produces:
@@ -37,7 +37,7 @@ func ListTrackedTimes(ctx *context.APIContext) {
 	//   description: name of the repo
 	//   type: string
 	//   required: true
-	// - name: repo
+	// - name: id
 	//   in: path
 	//   description: index of the issue
 	//   type: integer
@@ -70,7 +70,7 @@ func ListTrackedTimes(ctx *context.APIContext) {
 
 // AddTime adds time manual to the given issue
 func AddTime(ctx *context.APIContext, form api.AddTimeOption) {
-	// swagger:operation Post /repos/{owner}/{repo}/issues/{index}/times issue issueAddTime
+	// swagger:operation Post /repos/{owner}/{repo}/issues/{id}/times issue issueAddTime
 	// ---
 	// summary: Add a tracked time to a issue
 	// consumes:
@@ -132,7 +132,7 @@ func AddTime(ctx *context.APIContext, form api.AddTimeOption) {
 
 // ListTrackedTimesByUser  lists all tracked times of the user
 func ListTrackedTimesByUser(ctx *context.APIContext) {
-	// swagger:operation GET /repos/{owner}/{repo}/times/{tracker} user userTrackedTimes
+	// swagger:operation GET /repos/{owner}/{repo}/times/{user} user userTrackedTimes
 	// ---
 	// summary: List a user's tracked times in a repo
 	// produces:
diff --git a/routers/api/v1/repo/milestone.go b/routers/api/v1/repo/milestone.go
index 3953b0c3c0..a138cb7a69 100644
--- a/routers/api/v1/repo/milestone.go
+++ b/routers/api/v1/repo/milestone.go
@@ -16,14 +16,25 @@ import (
 
 // ListMilestones list all the milestones for a repository
 func ListMilestones(ctx *context.APIContext) {
-	// swagger:operation GET /repos/{owner}/{repo}/milestones/{id} issue issueGetMilestone
+	// swagger:operation GET /repos/{owner}/{repo}/milestones issue issueGetMilestonesList
 	// ---
-	// summary: Get a milestone
+	// 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
 	// responses:
 	//   "200":
-	//     "$ref": "#/responses/Milestone"
+	//     "$ref": "#/responses/MilestoneList"
 	milestones, err := models.GetMilestonesByRepoID(ctx.Repo.Repository.ID)
 	if err != nil {
 		ctx.Error(500, "GetMilestonesByRepoID", err)
@@ -39,9 +50,9 @@ 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
+	// swagger:operation GET /repos/{owner}/{repo}/milestones/{id} issue issueGetMilestone
 	// ---
-	// summary: Get all of a repository's milestones
+	// summary: Get a milestone
 	// produces:
 	// - application/json
 	// parameters:
@@ -55,25 +66,14 @@ func GetMilestone(ctx *context.APIContext) {
 	//   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
+	//   description: id of the milestone
 	//   type: integer
 	//   required: true
 	// responses:
 	//   "200":
-	//     "$ref": "#/responses/MilestoneList"
+	//     "$ref": "#/responses/Milestone"
 	milestone, err := models.GetMilestoneByRepoID(ctx.Repo.Repository.ID, ctx.ParamsInt64(":id"))
 	if err != nil {
 		if models.IsErrMilestoneNotExist(err) {
@@ -152,6 +152,11 @@ func EditMilestone(ctx *context.APIContext, form api.EditMilestoneOption) {
 	//   description: name of the repo
 	//   type: string
 	//   required: true
+	// - name: id
+	//   in: path
+	//   description: id of the milestone
+	//   type: integer
+	//   required: true
 	// - name: body
 	//   in: body
 	//   schema:
@@ -202,7 +207,7 @@ func DeleteMilestone(ctx *context.APIContext) {
 	//   description: name of the repo
 	//   type: string
 	//   required: true
-	// - name: body
+	// - name: id
 	//   in: path
 	//   description: id of the milestone to delete
 	//   type: integer
diff --git a/routers/api/v1/repo/repo.go b/routers/api/v1/repo/repo.go
index 9f64dda61d..ccfe0440c8 100644
--- a/routers/api/v1/repo/repo.go
+++ b/routers/api/v1/repo/repo.go
@@ -508,13 +508,13 @@ func TopicSearch(ctx *context.Context) {
 	// ---
 	// summary: search topics via keyword
 	// produces:
-	// - application/json
+	//   - application/json
 	// parameters:
-	// - name: keyword
-	//   in: path
-	//   description: id of the repo to get
-	//   type: integer
-	//   required: true
+	//   - name: q
+	//     in: query
+	//     description: keywords to search
+	//     required: true
+	//     type: string
 	// responses:
 	//   "200":
 	//     "$ref": "#/responses/Repository"
diff --git a/routers/api/v1/swagger/options.go b/routers/api/v1/swagger/options.go
index 8d9363fe91..4f2461f465 100644
--- a/routers/api/v1/swagger/options.go
+++ b/routers/api/v1/swagger/options.go
@@ -15,55 +15,87 @@ import (
 // parameterBodies
 // swagger:response parameterBodies
 type swaggerParameterBodies struct {
+	// in:body
 	AddCollaboratorOption api.AddCollaboratorOption
 
+	// in:body
 	CreateEmailOption api.CreateEmailOption
+	// in:body
 	DeleteEmailOption api.DeleteEmailOption
 
+	// in:body
 	CreateHookOption api.CreateHookOption
-	EditHookOption   api.EditHookOption
+	// in:body
+	EditHookOption api.EditHookOption
 
+	// in:body
 	CreateIssueOption api.CreateIssueOption
-	EditIssueOption   api.EditIssueOption
+	// in:body
+	EditIssueOption api.EditIssueOption
 
+	// in:body
 	CreateIssueCommentOption api.CreateIssueCommentOption
-	EditIssueCommentOption   api.EditIssueCommentOption
+	// in:body
+	EditIssueCommentOption api.EditIssueCommentOption
 
+	// in:body
 	IssueLabelsOption api.IssueLabelsOption
 
+	// in:body
 	CreateKeyOption api.CreateKeyOption
 
+	// in:body
 	CreateLabelOption api.CreateLabelOption
-	EditLabelOption   api.EditLabelOption
+	// in:body
+	EditLabelOption api.EditLabelOption
 
+	// in:body
 	MarkdownOption api.MarkdownOption
 
+	// in:body
 	CreateMilestoneOption api.CreateMilestoneOption
-	EditMilestoneOption   api.EditMilestoneOption
+	// in:body
+	EditMilestoneOption api.EditMilestoneOption
 
+	// in:body
 	CreateOrgOption api.CreateOrgOption
-	EditOrgOption   api.EditOrgOption
+	// in:body
+	EditOrgOption api.EditOrgOption
 
+	// in:body
 	CreatePullRequestOption api.CreatePullRequestOption
-	EditPullRequestOption   api.EditPullRequestOption
+	// in:body
+	EditPullRequestOption api.EditPullRequestOption
 
+	// in:body
 	CreateReleaseOption api.CreateReleaseOption
-	EditReleaseOption   api.EditReleaseOption
+	// in:body
+	EditReleaseOption api.EditReleaseOption
 
+	// in:body
 	CreateRepoOption api.CreateRepoOption
+	// in:body
 	CreateForkOption api.CreateForkOption
 
+	// in:body
 	CreateStatusOption api.CreateStatusOption
 
+	// in:body
 	CreateTeamOption api.CreateTeamOption
-	EditTeamOption   api.EditTeamOption
+	// in:body
+	EditTeamOption api.EditTeamOption
 
+	// in:body
 	AddTimeOption api.AddTimeOption
 
+	// in:body
 	CreateUserOption api.CreateUserOption
-	EditUserOption   api.EditUserOption
+	// in:body
+	EditUserOption api.EditUserOption
 
+	// in:body
 	MigrateRepoForm auth.MigrateRepoForm
 
+	// in:body
 	EditAttachmentOptions api.EditAttachmentOptions
 }
diff --git a/routers/api/v1/swagger/repo.go b/routers/api/v1/swagger/repo.go
index 97837dfc24..9decc8f588 100644
--- a/routers/api/v1/swagger/repo.go
+++ b/routers/api/v1/swagger/repo.go
@@ -102,6 +102,7 @@ type swaggerResponseWatchInfo struct {
 // SearchResults
 // swagger:response SearchResults
 type swaggerResponseSearchResults struct {
+	// in:body
 	Body api.SearchResults `json:"body"`
 }
 
diff --git a/routers/api/v1/user/app.go b/routers/api/v1/user/app.go
index e1f75de683..fc4118649c 100644
--- a/routers/api/v1/user/app.go
+++ b/routers/api/v1/user/app.go
@@ -18,6 +18,12 @@ func ListAccessTokens(ctx *context.APIContext) {
 	// summary: List the authenticated user's access tokens
 	// produces:
 	// - application/json
+	// parameters:
+	// - name: username
+	//   in: path
+	//   description: username of user
+	//   type: string
+	//   required: true
 	// responses:
 	//   "200":
 	//     "$ref": "#/responses/AccessTokenList"
@@ -46,6 +52,12 @@ func CreateAccessToken(ctx *context.APIContext, form api.CreateAccessTokenOption
 	// - application/json
 	// produces:
 	// - application/json
+	// parameters:
+	// - name: username
+	//   in: path
+	//   description: username of user
+	//   type: string
+	//   required: true
 	// responses:
 	//   "200":
 	//     "$ref": "#/responses/AccessToken"
diff --git a/routers/api/v1/user/follower.go b/routers/api/v1/user/follower.go
index 49d13cc380..284b7323c3 100644
--- a/routers/api/v1/user/follower.go
+++ b/routers/api/v1/user/follower.go
@@ -119,11 +119,11 @@ func checkUserFollowing(ctx *context.APIContext, u *models.User, followID int64)
 
 // CheckMyFollowing whether the given user is followed by the authenticated user
 func CheckMyFollowing(ctx *context.APIContext) {
-	// swagger:operation GET /user/following/{followee} user userCurrentCheckFollowing
+	// swagger:operation GET /user/following/{username} user userCurrentCheckFollowing
 	// ---
 	// summary: Check whether a user is followed by the authenticated user
 	// parameters:
-	// - name: followee
+	// - name: username
 	//   in: path
 	//   description: username of followed user
 	//   type: string