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.

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:

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:

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

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:

routers/api/v1/repo/milestone.go

@@ -16,30 +16,7 @@ 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)
-		return
-	}
-
-	apiMilestones := make([]*api.Milestone, len(milestones))
-	for i := range milestones {
-		apiMilestones[i] = milestones[i].APIFormat()
-	}
-	ctx.JSON(200, &apiMilestones)
-}
-
-// 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 issue issueGetMilestonesList
 	// ---
 	// summary: Get all of a repository's milestones
 	// produces:
@@ -55,6 +32,29 @@ func GetMilestone(ctx *context.APIContext) {
 	//   description: name of the repo
 	//   type: string
 	//   required: true
+	// responses:
+	//   "200":
+	//     "$ref": "#/responses/MilestoneList"
+	milestones, err := models.GetMilestonesByRepoID(ctx.Repo.Repository.ID)
+	if err != nil {
+		ctx.Error(500, "GetMilestonesByRepoID", err)
+		return
+	}
+
+	apiMilestones := make([]*api.Milestone, len(milestones))
+	for i := range milestones {
+		apiMilestones[i] = milestones[i].APIFormat()
+	}
+	ctx.JSON(200, &apiMilestones)
+}
+
+// GetMilestone get a milestone for a repository
+func GetMilestone(ctx *context.APIContext) {
+	// swagger:operation GET /repos/{owner}/{repo}/milestones/{id} issue issueGetMilestone
+	// ---
+	// summary: Get a milestone
+	// produces:
+	// - application/json
 	// parameters:
 	// - name: owner
 	//   in: path
@@ -68,12 +68,12 @@ func GetMilestone(ctx *context.APIContext) {
 	//   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

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"