From f26f4a7e01f9c380c261fa5bc21bd7e48f2f2f9f Mon Sep 17 00:00:00 2001 From: Ethan Koenig Date: Sun, 12 Nov 2017 23:02:25 -0800 Subject: 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 --- routers/api/v1/user/gpg_key.go | 133 ++++++++++++++++++++++++----------------- 1 file changed, 77 insertions(+), 56 deletions(-) (limited to 'routers/api/v1/user/gpg_key.go') 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) } -- cgit v1.2.3