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, 77 insertions, 56 deletions

diff --git a/routers/api/v1/user/gpg_key.go b/routers/api/v1/user/gpg_key.go
index 96ff6e88ba..a955f3ff14 100644
--- a/routers/api/v1/user/gpg_key.go
+++ b/routers/api/v1/user/gpg_key.go
@@ -34,15 +34,20 @@ func listGPGKeys(ctx *context.APIContext, uid int64) {
 
 //ListGPGKeys get the GPG key list of a user
 func ListGPGKeys(ctx *context.APIContext) {
-	// swagger:route GET /users/{username}/gpg_keys user userListGPGKeys
-	//
-	//     Produces:
-	//     - application/json
-	//
-	//     Responses:
-	//       200: GPGKeyList
-	//       500: error
-
+	// swagger:operation GET /users/{username}/gpg_keys user userListGPGKeys
+	// ---
+	// summary: List the given user's GPG keys
+	// produces:
+	// - application/json
+	// parameters:
+	// - name: username
+	//   in: path
+	//   description: username of user
+	//   type: string
+	//   required: true
+	// responses:
+	//   "200":
+	//     "$ref": "#/responses/GPGKeyList"
 	user := GetUserByParams(ctx)
 	if ctx.Written() {
 		return
@@ -50,32 +55,37 @@ func ListGPGKeys(ctx *context.APIContext) {
 	listGPGKeys(ctx, user.ID)
 }
 
-//ListMyGPGKeys get the GPG key list of the logged user
+//ListMyGPGKeys get the GPG key list of the authenticated user
 func ListMyGPGKeys(ctx *context.APIContext) {
-	// swagger:route GET /user/gpg_keys user userCurrentListGPGKeys
-	//
-	//     Produces:
-	//     - application/json
-	//
-	//     Responses:
-	//       200: GPGKeyList
-	//       500: error
-
+	// swagger:operation GET /user/gpg_keys user userCurrentListGPGKeys
+	// ---
+	// summary: List the authenticated user's GPG keys
+	// produces:
+	// - application/json
+	// responses:
+	//   "200":
+	//     "$ref": "#/responses/GPGKeyList"
 	listGPGKeys(ctx, ctx.User.ID)
 }
 
 //GetGPGKey get the GPG key based on a id
 func GetGPGKey(ctx *context.APIContext) {
-	// swagger:route GET /user/gpg_keys/{id} user userCurrentGetGPGKey
-	//
-	//     Produces:
-	//     - application/json
-	//
-	//     Responses:
-	//       200: GPGKey
-	//       404: notFound
-	//       500: error
-
+	// swagger:operation GET /user/gpg_keys/{id} user userCurrentGetGPGKey
+	// ---
+	// summary: Get a GPG key
+	// produces:
+	// - application/json
+	// parameters:
+	// - name: id
+	//   in: path
+	//   description: id of key to get
+	//   type: integer
+	//   required: true
+	// responses:
+	//   "200":
+	//     "$ref": "#/responses/GPGKey"
+	//   "404":
+	//     "$ref": "#/responses/notFound"
 	key, err := models.GetGPGKeyByID(ctx.ParamsInt64(":id"))
 	if err != nil {
 		if models.IsErrGPGKeyNotExist(err) {
@@ -98,36 +108,47 @@ func CreateUserGPGKey(ctx *context.APIContext, form api.CreateGPGKeyOption, uid
 	ctx.JSON(201, convert.ToGPGKey(key))
 }
 
-//CreateGPGKey associate a GPG key to the current user
-func CreateGPGKey(ctx *context.APIContext, form api.CreateGPGKeyOption) {
-	// swagger:route POST /user/gpg_keys user userCurrentPostGPGKey
-	//
-	//     Consumes:
-	//     - application/json
-	//
-	//     Produces:
-	//     - application/json
-	//
-	//     Responses:
-	//       201: GPGKey
-	//       422: validationError
-	//       500: error
+// swagger:parameters userCurrentPostGPGKey
+type swaggerUserCurrentPostGPGKey struct {
+	// in:body
+	Form api.CreateGPGKeyOption
+}
 
+//CreateGPGKey create a GPG key belonging to the authenticated user
+func CreateGPGKey(ctx *context.APIContext, form api.CreateGPGKeyOption) {
+	// swagger:operation POST /user/gpg_keys user userCurrentPostGPGKey
+	// ---
+	// summary: Create a GPG key
+	// consumes:
+	// - application/json
+	// produces:
+	// - application/json
+	// responses:
+	//   "201":
+	//     "$ref": "#/responses/GPGKey"
+	//   "422":
+	//     "$ref": "#/responses/validationError"
 	CreateUserGPGKey(ctx, form, ctx.User.ID)
 }
 
-//DeleteGPGKey remove a GPG key associated to the current user
+//DeleteGPGKey remove a GPG key belonging to the authenticated user
 func DeleteGPGKey(ctx *context.APIContext) {
-	// swagger:route DELETE /user/gpg_keys/{id} user userCurrentDeleteGPGKey
-	//
-	//     Produces:
-	//     - application/json
-	//
-	//     Responses:
-	//       204: empty
-	//       403: forbidden
-	//       500: error
-
+	// swagger:operation DELETE /user/gpg_keys/{id} user userCurrentDeleteGPGKey
+	// ---
+	// summary: Remove a GPG key
+	// produces:
+	// - application/json
+	// parameters:
+	// - name: id
+	//   in: path
+	//   description: id of key to delete
+	//   type: integer
+	//   required: true
+	// responses:
+	//   "204":
+	//     "$ref": "#/responses/empty"
+	//   "403":
+	//     "$ref": "#/responses/forbidden"
 	if err := models.DeleteGPGKey(ctx.User, ctx.ParamsInt64(":id")); err != nil {
 		if models.IsErrGPGKeyAccessDenied(err) {
 			ctx.Error(403, "", "You do not have access to this key")
@@ -144,9 +165,9 @@ func DeleteGPGKey(ctx *context.APIContext) {
 func HandleAddGPGKeyError(ctx *context.APIContext, err error) {
 	switch {
 	case models.IsErrGPGKeyAccessDenied(err):
-		ctx.Error(422, "", "You do not have access to this gpg key")
+		ctx.Error(422, "", "You do not have access to this GPG key")
 	case models.IsErrGPGKeyIDAlreadyUsed(err):
-		ctx.Error(422, "", "A key with the same keyid is already in database")
+		ctx.Error(422, "", "A key with the same id already exists")
 	default:
 		ctx.Error(500, "AddGPGKey", err)
 	}