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, 139 insertions, 0 deletions

diff --git a/routers/api/v1/repo/issue_label.go b/routers/api/v1/repo/issue_label.go
index 2eec743e70..fde919e506 100644
--- a/routers/api/v1/repo/issue_label.go
+++ b/routers/api/v1/repo/issue_label.go
@@ -13,6 +13,32 @@ import (
 
 // ListIssueLabels list all the labels of an issue
 func ListIssueLabels(ctx *context.APIContext) {
+	// swagger:operation GET /repos/{owner}/{repo}/issues/{index}/labels issue issueGetLabels
+	// ---
+	// summary: Get an issue's labels
+	// 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
+	// - name: index
+	//   in: path
+	//   description: index of the issue
+	//   type: integer
+	//   required: true
+	// responses:
+	//   "200":
+	//     "$ref": "#/responses/LabelList"
+	//   "404":
+	//     "$ref": "#/responses/notFound"
 	issue, err := models.GetIssueByIndex(ctx.Repo.Repository.ID, ctx.ParamsInt64(":index"))
 	if err != nil {
 		if models.IsErrIssueNotExist(err) {
@@ -32,6 +58,36 @@ func ListIssueLabels(ctx *context.APIContext) {
 
 // AddIssueLabels add labels for an issue
 func AddIssueLabels(ctx *context.APIContext, form api.IssueLabelsOption) {
+	// swagger:operation POST /repos/{owner}/{repo}/issue/{index}/labels issue issueAddLabel
+	// ---
+	// summary: Add a label to an issue
+	// consumes:
+	// - application/json
+	// 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
+	// - name: index
+	//   in: path
+	//   description: index of the issue
+	//   type: integer
+	//   required: true
+	// - name: body
+	//   in: body
+	//   schema:
+	//     "$ref": "#/definitions/IssueLabelsOption"
+	// responses:
+	//   "200":
+	//     "$ref": "#/responses/LabelList"
 	if !ctx.Repo.IsWriter() {
 		ctx.Status(403)
 		return
@@ -73,6 +129,35 @@ func AddIssueLabels(ctx *context.APIContext, form api.IssueLabelsOption) {
 
 // DeleteIssueLabel delete a label for an issue
 func DeleteIssueLabel(ctx *context.APIContext) {
+	// swagger:operation DELETE /repos/{owner}/{repo}/issue/{index}/labels/{id} issue issueRemoveLabel
+	// ---
+	// summary: Remove a label from an issue
+	// 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
+	// - name: index
+	//   in: path
+	//   description: index of the issue
+	//   type: integer
+	//   required: true
+	// - name: id
+	//   in: path
+	//   description: id of the label to remove
+	//   type: integer
+	//   required: true
+	// responses:
+	//   "204":
+	//     "$ref": "#/responses/empty"
 	if !ctx.Repo.IsWriter() {
 		ctx.Status(403)
 		return
@@ -108,6 +193,36 @@ func DeleteIssueLabel(ctx *context.APIContext) {
 
 // ReplaceIssueLabels replace labels for an issue
 func ReplaceIssueLabels(ctx *context.APIContext, form api.IssueLabelsOption) {
+	// swagger:operation PUT /repos/{owner}/{repo}/issue/{index}/labels issue issueReplaceLabels
+	// ---
+	// summary: Replace an issue's labels
+	// consumes:
+	// - application/json
+	// 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
+	// - name: index
+	//   in: path
+	//   description: index of the issue
+	//   type: integer
+	//   required: true
+	// - name: body
+	//   in: body
+	//   schema:
+	//     "$ref": "#/definitions/IssueLabelsOption"
+	// responses:
+	//   "200":
+	//     "$ref": "#/responses/LabelList"
 	if !ctx.Repo.IsWriter() {
 		ctx.Status(403)
 		return
@@ -149,6 +264,30 @@ func ReplaceIssueLabels(ctx *context.APIContext, form api.IssueLabelsOption) {
 
 // ClearIssueLabels delete all the labels for an issue
 func ClearIssueLabels(ctx *context.APIContext) {
+	// swagger:operation DELETE /repos/{owner}/{repo}/issue/{index}/labels issue issueClearLabels
+	// ---
+	// summary: Remove all labels from an issue
+	// 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
+	// - name: index
+	//   in: path
+	//   description: index of the issue
+	//   type: integer
+	//   required: true
+	// responses:
+	//   "204":
+	//     "$ref": "#/responses/empty"
 	if !ctx.Repo.IsWriter() {
 		ctx.Status(403)
 		return