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

diff --git a/routers/api/v1/repo/label.go b/routers/api/v1/repo/label.go
index c932fb1585..cb724c7182 100644
--- a/routers/api/v1/repo/label.go
+++ b/routers/api/v1/repo/label.go
@@ -15,6 +15,25 @@ import (
 
 // ListLabels list all the labels of a repository
 func ListLabels(ctx *context.APIContext) {
+	// swagger:operation GET /repos/{owner}/{repo}/labels issue issueListLabels
+	// ---
+	// summary: Get all of a repository'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
+	// responses:
+	//   "200":
+	//     "$ref": "#/responses/LabelList"
 	labels, err := models.GetLabelsByRepoID(ctx.Repo.Repository.ID, ctx.Query("sort"))
 	if err != nil {
 		ctx.Error(500, "GetLabelsByRepoID", err)
@@ -30,6 +49,30 @@ func ListLabels(ctx *context.APIContext) {
 
 // GetLabel get label by repository and label id
 func GetLabel(ctx *context.APIContext) {
+	// swagger:operation GET /repos/{owner}/{repo}/labels/{id} issue issueGetLabel
+	// ---
+	// summary: Get a single label
+	// 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: id
+	//   in: path
+	//   description: id of the label to get
+	//   type: integer
+	//   required: true
+	// responses:
+	//   "200":
+	//     "$ref": "#/responses/Label"
 	var (
 		label *models.Label
 		err   error
@@ -54,6 +97,31 @@ func GetLabel(ctx *context.APIContext) {
 
 // CreateLabel create a label for a repository
 func CreateLabel(ctx *context.APIContext, form api.CreateLabelOption) {
+	// swagger:operation POST /repos/{owner}/{repo}/labels issue issueCreateLabel
+	// ---
+	// summary: Create a label
+	// 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: body
+	//   in: body
+	//   schema:
+	//     "$ref": "#/definitions/CreateLabelOption"
+	// responses:
+	//   "201":
+	//     "$ref": "#/responses/Label"
 	if !ctx.Repo.IsWriter() {
 		ctx.Status(403)
 		return
@@ -73,6 +141,36 @@ func CreateLabel(ctx *context.APIContext, form api.CreateLabelOption) {
 
 // EditLabel modify a label for a repository
 func EditLabel(ctx *context.APIContext, form api.EditLabelOption) {
+	// swagger:operation PATCH /repos/{owner}/{repo}/labels/{id} issue issueEditLabel
+	// ---
+	// summary: Update a label
+	// 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: id
+	//   in: path
+	//   description: id of the label to edit
+	//   type: integer
+	//   required: true
+	// - name: body
+	//   in: body
+	//   schema:
+	//     "$ref": "#/definitions/EditLabelOption"
+	// responses:
+	//   "200":
+	//     "$ref": "#/responses/Label"
 	if !ctx.Repo.IsWriter() {
 		ctx.Status(403)
 		return
@@ -103,6 +201,28 @@ func EditLabel(ctx *context.APIContext, form api.EditLabelOption) {
 
 // DeleteLabel delete a label for a repository
 func DeleteLabel(ctx *context.APIContext) {
+	// swagger:operation DELETE /repos/{owner}/{repo}/labels/{id} issue issueDeleteLabel
+	// ---
+	// summary: Delete a label
+	// 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 label to delete
+	//   type: integer
+	//   required: true
+	// responses:
+	//   "204":
+	//     "$ref": "#/responses/empty"
 	if !ctx.Repo.IsWriter() {
 		ctx.Status(403)
 		return