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

diff --git a/routers/api/v1/repo/issue.go b/routers/api/v1/repo/issue.go
index 2debe67c3b..08815ee074 100644
--- a/routers/api/v1/repo/issue.go
+++ b/routers/api/v1/repo/issue.go
@@ -18,6 +18,33 @@ import (
 
 // ListIssues list the issues of a repository
 func ListIssues(ctx *context.APIContext) {
+	// swagger:operation GET /repos/{owner}/{repo}/issues issue issueListIssues
+	// ---
+	// summary: List a repository's issues
+	// 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: state
+	//   in: query
+	//   description: whether issue is open or closed
+	//   type: string
+	// - name: page
+	//   in: query
+	//   description: page number of requested issues
+	//   type: integer
+	// responses:
+	//   "200":
+	//     "$ref": "#/responses/IssueList"
 	var isClosed util.OptionalBool
 	switch ctx.Query("state") {
 	case "closed":
@@ -50,6 +77,30 @@ func ListIssues(ctx *context.APIContext) {
 
 // GetIssue get an issue of a repository
 func GetIssue(ctx *context.APIContext) {
+	// swagger:operation GET /repos/{owner}/{repo}/issues/{id} issue issueGetIssue
+	// ---
+	// summary: Get an issue by id
+	// 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 issue to get
+	//   type: integer
+	//   required: true
+	// responses:
+	//   "200":
+	//     "$ref": "#/responses/Issue"
 	issue, err := models.GetIssueByIndex(ctx.Repo.Repository.ID, ctx.ParamsInt64(":index"))
 	if err != nil {
 		if models.IsErrIssueNotExist(err) {
@@ -64,6 +115,31 @@ func GetIssue(ctx *context.APIContext) {
 
 // CreateIssue create an issue of a repository
 func CreateIssue(ctx *context.APIContext, form api.CreateIssueOption) {
+	// swagger:operation POST /repos/{owner}/{repo}/issues issue issueCreateIssue
+	// ---
+	// summary: Create 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: body
+	//   in: body
+	//   schema:
+	//     "$ref": "#/definitions/CreateIssueOption"
+	// responses:
+	//   "201":
+	//     "$ref": "#/responses/Issue"
 	issue := &models.Issue{
 		RepoID:   ctx.Repo.Repository.ID,
 		Title:    form.Title,
@@ -114,6 +190,36 @@ func CreateIssue(ctx *context.APIContext, form api.CreateIssueOption) {
 
 // EditIssue modify an issue of a repository
 func EditIssue(ctx *context.APIContext, form api.EditIssueOption) {
+	// swagger:operation PATCH /repos/{owner}/{repo}/issues/{id} issue issueEditIssue
+	// ---
+	// summary: Edit 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: id
+	//   in: path
+	//   description: id of the issue to edit
+	//   type: integer
+	//   required: true
+	// - name: body
+	//   in: body
+	//   schema:
+	//     "$ref": "#/definitions/EditIssueOption"
+	// responses:
+	//   "201":
+	//     "$ref": "#/responses/Issue"
 	issue, err := models.GetIssueByIndex(ctx.Repo.Repository.ID, ctx.ParamsInt64(":index"))
 	if err != nil {
 		if models.IsErrIssueNotExist(err) {