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, 72 insertions, 36 deletions

diff --git a/routers/api/v1/user/watch.go b/routers/api/v1/user/watch.go
index 18628c91d1..b10831f5f2 100644
--- a/routers/api/v1/user/watch.go
+++ b/routers/api/v1/user/watch.go
@@ -33,15 +33,19 @@ func getWatchedRepos(userID int64, private bool) ([]*api.Repository, error) {
 
 // GetWatchedRepos returns the repos that the user specified in ctx is watching
 func GetWatchedRepos(ctx *context.APIContext) {
-	// swagger:route GET /users/{username}/subscriptions user userListSubscriptions
-	//
-	//     Produces:
-	//     - application/json
-	//
-	//     Responses:
-	//       200: RepositoryList
-	//       500: error
-
+	// swagger:operation GET /users/{username}/subscriptions user userListSubscriptions
+	// ---
+	// summary: List the repositories watched by a user
+	// produces:
+	// - application/json
+	// parameters:
+	// - name: username
+	//   type: string
+	//   in: path
+	//   description: username of the user
+	// responses:
+	//   "200":
+	//     "$ref": "#/responses/RepositoryList"
 	user := GetUserByParams(ctx)
 	private := user.ID == ctx.User.ID
 	repos, err := getWatchedRepos(user.ID, private)
@@ -53,15 +57,14 @@ func GetWatchedRepos(ctx *context.APIContext) {
 
 // GetMyWatchedRepos returns the repos that the authenticated user is watching
 func GetMyWatchedRepos(ctx *context.APIContext) {
-	// swagger:route GET /user/subscriptions user userCurrentListSubscriptions
-	//
-	//     Produces:
-	//     - application/json
-	//
-	//     Responses:
-	//       200: RepositoryList
-	//       500: error
-
+	// swagger:operation GET /user/subscriptions user userCurrentListSubscriptions
+	// ---
+	// summary: List repositories watched by the authenticated user
+	// produces:
+	// - application/json
+	// responses:
+	//   "200":
+	//     "$ref": "#/responses/RepositoryList"
 	repos, err := getWatchedRepos(ctx.User.ID, true)
 	if err != nil {
 		ctx.Error(500, "getWatchedRepos", err)
@@ -72,12 +75,23 @@ func GetMyWatchedRepos(ctx *context.APIContext) {
 // IsWatching returns whether the authenticated user is watching the repo
 // specified in ctx
 func IsWatching(ctx *context.APIContext) {
-	// swagger:route GET /repos/{username}/{reponame}/subscription repository userCurrentCheckSubscription
-	//
-	//     Responses:
-	//       200: WatchInfo
-	//       404: notFound
-
+	// swagger:operation GET /repos/{owner}/{repo}/subscription repository userCurrentCheckSubscription
+	// ---
+	// summary: Check if the current user is watching a repo
+	// 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/WatchInfo"
 	if models.IsWatching(ctx.User.ID, ctx.Repo.Repository.ID) {
 		ctx.JSON(200, api.WatchInfo{
 			Subscribed:    true,
@@ -94,12 +108,23 @@ func IsWatching(ctx *context.APIContext) {
 
 // Watch the repo specified in ctx, as the authenticated user
 func Watch(ctx *context.APIContext) {
-	// swagger:route PUT /repos/{username}/{reponame}/subscription repository userCurrentPutSubscription
-	//
-	//     Responses:
-	//       200: WatchInfo
-	//       500: error
-
+	// swagger:operation PUT /repos/{owner}/{repo}/subscription repository userCurrentPutSubscription
+	// ---
+	// summary: Watch a repo
+	// 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/WatchInfo"
 	err := models.WatchRepo(ctx.User.ID, ctx.Repo.Repository.ID, true)
 	if err != nil {
 		ctx.Error(500, "WatchRepo", err)
@@ -118,12 +143,23 @@ func Watch(ctx *context.APIContext) {
 
 // Unwatch the repo specified in ctx, as the authenticated user
 func Unwatch(ctx *context.APIContext) {
-	// swagger:route DELETE /repos/{username}/{reponame}/subscription repository userCurrentDeleteSubscription
-	//
-	//     Responses:
-	//       204: empty
-	//       500: error
-
+	// swagger:operation DELETE /repos/{owner}/{repo}/subscription repository userCurrentDeleteSubscription
+	// ---
+	// summary: Unwatch a repo
+	// 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:
+	//   "204":
+	//     "$ref": "#/responses/empty"
 	err := models.WatchRepo(ctx.User.ID, ctx.Repo.Repository.ID, false)
 	if err != nil {
 		ctx.Error(500, "UnwatchRepo", err)