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

diff --git a/routers/api/v1/repo/milestone.go b/routers/api/v1/repo/milestone.go
index ef32ed8989..0e597a9db0 100644
--- a/routers/api/v1/repo/milestone.go
+++ b/routers/api/v1/repo/milestone.go
@@ -15,6 +15,14 @@ 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)
@@ -30,6 +38,41 @@ 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
+	// ---
+	// 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
+	// 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
+	//   type: integer
+	//   required: true
+	// responses:
+	//   "200":
+	//     "$ref": "#/responses/MilestoneList"
 	milestone, err := models.GetMilestoneByRepoID(ctx.Repo.Repository.ID, ctx.ParamsInt64(":id"))
 	if err != nil {
 		if models.IsErrMilestoneNotExist(err) {
@@ -44,6 +87,31 @@ func GetMilestone(ctx *context.APIContext) {
 
 // CreateMilestone create a milestone for a repository
 func CreateMilestone(ctx *context.APIContext, form api.CreateMilestoneOption) {
+	// swagger:operation POST /repos/{owner}/{repo}/milestones issue issueCreateMilestone
+	// ---
+	// summary: Create a milestone
+	// 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/CreateMilestoneOption"
+	// responses:
+	//   "201":
+	//     "$ref": "#/responses/Milestone"
 	if form.Deadline == nil {
 		defaultDeadline, _ := time.ParseInLocation("2006-01-02", "9999-12-31", time.Local)
 		form.Deadline = &defaultDeadline
@@ -65,6 +133,31 @@ func CreateMilestone(ctx *context.APIContext, form api.CreateMilestoneOption) {
 
 // EditMilestone modify a milestone for a repository
 func EditMilestone(ctx *context.APIContext, form api.EditMilestoneOption) {
+	// swagger:operation PATCH /repos/{owner}/{repo}/milestones/{id} issue issueEditMilestone
+	// ---
+	// summary: Update a milestone
+	// 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/EditMilestoneOption"
+	// responses:
+	//   "200":
+	//     "$ref": "#/responses/Milestone"
 	milestone, err := models.GetMilestoneByRepoID(ctx.Repo.Repository.ID, ctx.ParamsInt64(":id"))
 	if err != nil {
 		if models.IsErrMilestoneNotExist(err) {
@@ -94,6 +187,28 @@ func EditMilestone(ctx *context.APIContext, form api.EditMilestoneOption) {
 
 // DeleteMilestone delete a milestone for a repository
 func DeleteMilestone(ctx *context.APIContext) {
+	// swagger:operation DELETE /repos/{owner}/{repo}/milestones/{id} issue issueDeleteMilestone
+	// ---
+	// summary: Delete a milestone
+	// 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: path
+	//   description: id of the milestone to delete
+	//   type: integer
+	//   required: true
+	// responses:
+	//   "204":
+	//     "$ref": "#/responses/empty"
 	if err := models.DeleteMilestoneByRepoID(ctx.Repo.Repository.ID, ctx.ParamsInt64(":id")); err != nil {
 		ctx.Error(500, "DeleteMilestoneByRepoID", err)
 		return