davrot/forgejo_backup
1
0
Fork 0
mirror of https://codeberg.org/davrot/forgejo.git synced 2025-05-28 12:00:01 +02:00
Code Issues Projects Releases Packages Wiki Activity Actions

Update swagger documentation (#2899)

Browse source 
* Update swagger documentation

Add docs for missing endpoints
Add documentation for request parameters
Make parameter naming consistent
Fix response documentation

* Restore delete comments
This commit is contained in:
Ethan Koenig 2017-11-12 23:02:25 -08:00 • committed by Lauris BH
parent 4287d100b3
commit f26f4a7e01
72 changed files with 8875 additions and 2323 deletions
Download patch file Download diff file Expand all files Collapse all files

133
routers/api/v1/user/gpg_key.go
View file

@ -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)
}