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, 42 insertions, 28 deletions

diff --git a/routers/api/v1/user/user.go b/routers/api/v1/user/user.go
index 799cec0804..0453a455f4 100644
--- a/routers/api/v1/user/user.go
+++ b/routers/api/v1/user/user.go
@@ -17,15 +17,23 @@ import (
 
 // Search search users
 func Search(ctx *context.APIContext) {
-	// swagger:route GET /users/search user userSearch
-	//
-	//     Produces:
-	//     - application/json
-	//
-	//     Responses:
-	//       200: UserList
-	//       500: error
-
+	// swagger:operation GET /users/search user userSearch
+	// ---
+	// summary: Search for users
+	// produces:
+	// - application/json
+	// parameters:
+	// - name: q
+	//   in: query
+	//   description: keyword
+	//   type: string
+	// - name: limit
+	//   in: query
+	//   description: maximum number of users to return
+	//   type: integer
+	// responses:
+	//   "200":
+	//     "$ref": "#/responses/UserList"
 	opts := &models.SearchUserOptions{
 		Keyword:  strings.Trim(ctx.Query("q"), " "),
 		Type:     models.UserTypeIndividual,
@@ -65,16 +73,22 @@ func Search(ctx *context.APIContext) {
 
 // GetInfo get user's information
 func GetInfo(ctx *context.APIContext) {
-	// swagger:route GET /users/{username} user userGet
-	//
-	//     Produces:
-	//     - application/json
-	//
-	//     Responses:
-	//       200: User
-	//       404: notFound
-	//       500: error
-
+	// swagger:operation GET /users/{username} user userGet
+	// ---
+	// summary: Get a user
+	// produces:
+	// - application/json
+	// parameters:
+	// - name: username
+	//   in: path
+	//   description: username of user to get
+	//   type: string
+	//   required: true
+	// responses:
+	//   "200":
+	//     "$ref": "#/responses/User"
+	//   "404":
+	//     "$ref": "#/responses/notFound"
 	u, err := models.GetUserByName(ctx.Params(":username"))
 	if err != nil {
 		if models.IsErrUserNotExist(err) {
@@ -92,15 +106,15 @@ func GetInfo(ctx *context.APIContext) {
 	ctx.JSON(200, u.APIFormat())
 }
 
-// GetAuthenticatedUser get curent user's information
+// GetAuthenticatedUser get current user's information
 func GetAuthenticatedUser(ctx *context.APIContext) {
-	// swagger:route GET /user user userGetCurrent
-	//
-	//     Produces:
-	//     - application/json
-	//
-	//     Responses:
-	//       200: User
-
+	// swagger:operation GET /user user userGetCurrent
+	// ---
+	// summary: Get the authenticated user
+	// produces:
+	// - application/json
+	// responses:
+	//   "200":
+	//     "$ref": "#/responses/User"
 	ctx.JSON(200, ctx.User.APIFormat())
 }