luckyimnotanigger/forgejo
1
0
Fork 0
mirror of https://codeberg.org/forgejo/forgejo.git synced 2025-06-01 04:12:10 +00:00
Code Issues Projects Releases Packages Wiki Activity Actions 8

Improve Swagger documentation for user endpoints

Browse source
This commit is contained in:
JakobDev 2024-11-23 10:33:55 +01:00
parent 1316f4d338
commit b074e08f34
No known key found for this signature in database
GPG key ID: 39DEF62C3ED6DC4C
23 changed files with 703 additions and 2 deletions
Download patch file Download diff file Expand all files Collapse all files

4
routers/api/v1/org/org.go
View file

@ -68,6 +68,10 @@ func ListMyOrgs(ctx *context.APIContext) {
// responses:
// "200":
// "$ref": "#/responses/OrganizationList"
// "401":
// "$ref": "#/responses/unauthorized"
// "403":
// "$ref": "#/responses/forbidden"
// "404":
// "$ref": "#/responses/notFound"

4
routers/api/v1/org/team.go
View file

@ -91,6 +91,10 @@ func ListUserTeams(ctx *context.APIContext) {
// responses:
// "200":
// "$ref": "#/responses/TeamList"
// "401":
// "$ref": "#/responses/unauthorized"
// "403":
// "$ref": "#/responses/forbidden"
teams, count, err := organization.SearchTeam(ctx, &organization.SearchTeamOptions{
ListOptions: utils.GetListOptions(ctx),

4
routers/api/v1/repo/issue_stopwatch.go
View file

@ -217,6 +217,10 @@ func GetStopwatches(ctx *context.APIContext) {
// responses:
// "200":
// "$ref": "#/responses/StopWatchList"
// "401":
// "$ref": "#/responses/unauthorized"
// "403":
// "$ref": "#/responses/forbidden"
sws, err := issues_model.GetUserStopwatches(ctx, ctx.Doer.ID, utils.GetListOptions(ctx))
if err != nil {

4
routers/api/v1/repo/issue_tracked_time.go
View file

@ -599,6 +599,10 @@ func ListMyTrackedTimes(ctx *context.APIContext) {
// responses:
// "200":
// "$ref": "#/responses/TrackedTimeList"
// "401":
// "$ref": "#/responses/unauthorized"
// "403":
// "$ref": "#/responses/forbidden"
opts := &issues_model.FindTrackedTimesOptions{
ListOptions: utils.GetListOptions(ctx),

4
routers/api/v1/repo/repo.go
View file

@ -304,6 +304,10 @@ func Create(ctx *context.APIContext) {
// "$ref": "#/responses/Repository"
// "400":
// "$ref": "#/responses/error"
// "401":
// "$ref": "#/responses/unauthorized"
// "403":
// "$ref": "#/responses/forbidden"
// "409":
// description: The repository with the same name already exists.
// "413":

28
routers/api/v1/user/action.go
View file

@ -44,6 +44,10 @@ func CreateOrUpdateSecret(ctx *context.APIContext) {
// description: response when updating a secret
// "400":
// "$ref": "#/responses/error"
// "401":
// "$ref": "#/responses/unauthorized"
// "403":
// "$ref": "#/responses/forbidden"
// "404":
// "$ref": "#/responses/notFound"
@ -88,6 +92,10 @@ func DeleteSecret(ctx *context.APIContext) {
// description: delete one secret of the user
// "400":
// "$ref": "#/responses/error"
// "401":
// "$ref": "#/responses/unauthorized"
// "403":
// "$ref": "#/responses/forbidden"
// "404":
// "$ref": "#/responses/notFound"
@ -132,6 +140,10 @@ func CreateVariable(ctx *context.APIContext) {
// description: response when creating a variable
// "400":
// "$ref": "#/responses/error"
// "401":
// "$ref": "#/responses/unauthorized"
// "403":
// "$ref": "#/responses/forbidden"
// "404":
// "$ref": "#/responses/notFound"
@ -191,6 +203,10 @@ func UpdateVariable(ctx *context.APIContext) {
// description: response when updating a variable
// "400":
// "$ref": "#/responses/error"
// "401":
// "$ref": "#/responses/unauthorized"
// "403":
// "$ref": "#/responses/forbidden"
// "404":
// "$ref": "#/responses/notFound"
@ -244,6 +260,10 @@ func DeleteVariable(ctx *context.APIContext) {
// description: response when deleting a variable
// "400":
// "$ref": "#/responses/error"
// "401":
// "$ref": "#/responses/unauthorized"
// "403":
// "$ref": "#/responses/forbidden"
// "404":
// "$ref": "#/responses/notFound"
@ -279,6 +299,10 @@ func GetVariable(ctx *context.APIContext) {
// "$ref": "#/responses/ActionVariable"
// "400":
// "$ref": "#/responses/error"
// "401":
// "$ref": "#/responses/unauthorized"
// "403":
// "$ref": "#/responses/forbidden"
// "404":
// "$ref": "#/responses/notFound"
@ -326,6 +350,10 @@ func ListVariables(ctx *context.APIContext) {
// "$ref": "#/responses/VariableList"
// "400":
// "$ref": "#/responses/error"
// "401":
// "$ref": "#/responses/unauthorized"
// "403":
// "$ref": "#/responses/forbidden"
// "404":
// "$ref": "#/responses/notFound"

24
routers/api/v1/user/app.go
View file

@ -46,6 +46,8 @@ func ListAccessTokens(ctx *context.APIContext) {
// "$ref": "#/responses/AccessTokenList"
// "403":
// "$ref": "#/responses/forbidden"
// "404":
// "$ref": "#/responses/notFound"
opts := auth_model.ListAccessTokensOptions{UserID: ctx.ContextUser.ID, ListOptions: utils.GetListOptions(ctx)}
@ -95,6 +97,8 @@ func CreateAccessToken(ctx *context.APIContext) {
// "$ref": "#/responses/error"
// "403":
// "$ref": "#/responses/forbidden"
// "404":
// "$ref": "#/responses/notFound"
form := web.GetForm(ctx).(*api.CreateAccessTokenOption)
@ -224,6 +228,10 @@ func CreateOauth2Application(ctx *context.APIContext) {
// "$ref": "#/responses/OAuth2Application"
// "400":
// "$ref": "#/responses/error"
// "401":
// "$ref": "#/responses/unauthorized"
// "403":
// "$ref": "#/responses/forbidden"
data := web.GetForm(ctx).(*api.CreateOAuth2ApplicationOptions)
@ -266,6 +274,10 @@ func ListOauth2Applications(ctx *context.APIContext) {
// responses:
// "200":
// "$ref": "#/responses/OAuth2ApplicationList"
// "401":
// "$ref": "#/responses/unauthorized"
// "403":
// "$ref": "#/responses/forbidden"
apps, total, err := db.FindAndCount[auth_model.OAuth2Application](ctx, auth_model.FindOAuth2ApplicationsOptions{
ListOptions: utils.GetListOptions(ctx),
@ -303,6 +315,10 @@ func DeleteOauth2Application(ctx *context.APIContext) {
// responses:
// "204":
// "$ref": "#/responses/empty"
// "401":
// "$ref": "#/responses/unauthorized"
// "403":
// "$ref": "#/responses/forbidden"
// "404":
// "$ref": "#/responses/notFound"
appID := ctx.ParamsInt64(":id")
@ -335,6 +351,10 @@ func GetOauth2Application(ctx *context.APIContext) {
// responses:
// "200":
// "$ref": "#/responses/OAuth2Application"
// "401":
// "$ref": "#/responses/unauthorized"
// "403":
// "$ref": "#/responses/forbidden"
// "404":
// "$ref": "#/responses/notFound"
appID := ctx.ParamsInt64(":id")
@ -379,6 +399,10 @@ func UpdateOauth2Application(ctx *context.APIContext) {
// responses:
// "200":
// "$ref": "#/responses/OAuth2Application"
// "401":
// "$ref": "#/responses/unauthorized"
// "403":
// "$ref": "#/responses/forbidden"
// "404":
// "$ref": "#/responses/notFound"
appID := ctx.ParamsInt64(":id")

8
routers/api/v1/user/avatar.go
View file

@ -28,6 +28,10 @@ func UpdateAvatar(ctx *context.APIContext) {
// responses:
// "204":
// "$ref": "#/responses/empty"
// "401":
// "$ref": "#/responses/unauthorized"
// "403":
// "$ref": "#/responses/forbidden"
form := web.GetForm(ctx).(*api.UpdateUserAvatarOption)
content, err := base64.StdEncoding.DecodeString(form.Image)
@ -55,6 +59,10 @@ func DeleteAvatar(ctx *context.APIContext) {
// responses:
// "204":
// "$ref": "#/responses/empty"
// "401":
// "$ref": "#/responses/unauthorized"
// "403":
// "$ref": "#/responses/forbidden"
err := user_service.DeleteAvatar(ctx, ctx.Doer)
if err != nil {
ctx.Error(http.StatusInternalServerError, "DeleteAvatar", err)

12
routers/api/v1/user/email.go
View file

@ -27,6 +27,10 @@ func ListEmails(ctx *context.APIContext) {
// responses:
// "200":
// "$ref": "#/responses/EmailList"
// "401":
// "$ref": "#/responses/unauthorized"
// "403":
// "$ref": "#/responses/forbidden"
emails, err := user_model.GetEmailAddresses(ctx, ctx.Doer.ID)
if err != nil {
@ -55,6 +59,10 @@ func AddEmail(ctx *context.APIContext) {
// responses:
// '201':
// "$ref": "#/responses/EmailList"
// "401":
// "$ref": "#/responses/unauthorized"
// "403":
// "$ref": "#/responses/forbidden"
// "422":
// "$ref": "#/responses/validationError"
@ -112,6 +120,10 @@ func DeleteEmail(ctx *context.APIContext) {
// responses:
// "204":
// "$ref": "#/responses/empty"
// "401":
// "$ref": "#/responses/unauthorized"
// "403":
// "$ref": "#/responses/forbidden"
// "404":
// "$ref": "#/responses/notFound"

22
routers/api/v1/user/follower.go
View file

@ -53,6 +53,10 @@ func ListMyFollowers(ctx *context.APIContext) {
// responses:
// "200":
// "$ref": "#/responses/UserList"
// "401":
// "$ref": "#/responses/unauthorized"
// "403":
// "$ref": "#/responses/forbidden"
listUserFollowers(ctx, ctx.Doer)
}
@ -117,6 +121,10 @@ func ListMyFollowing(ctx *context.APIContext) {
// responses:
// "200":
// "$ref": "#/responses/UserList"
// "401":
// "$ref": "#/responses/unauthorized"
// "403":
// "$ref": "#/responses/forbidden"
listUserFollowing(ctx, ctx.Doer)
}
@ -173,6 +181,10 @@ func CheckMyFollowing(ctx *context.APIContext) {
// responses:
// "204":
// "$ref": "#/responses/empty"
// "401":
// "$ref": "#/responses/unauthorized"
// "403":
// "$ref": "#/responses/forbidden"
// "404":
// "$ref": "#/responses/notFound"
@ -222,10 +234,12 @@ func Follow(ctx *context.APIContext) {
// responses:
// "204":
// "$ref": "#/responses/empty"
// "404":
// "$ref": "#/responses/notFound"
// "401":
// "$ref": "#/responses/unauthorized"
// "403":
// "$ref": "#/responses/forbidden"
// "404":
// "$ref": "#/responses/notFound"
if err := user_model.FollowUser(ctx, ctx.Doer.ID, ctx.ContextUser.ID); err != nil {
if errors.Is(err, user_model.ErrBlockedByUser) {
@ -252,6 +266,10 @@ func Unfollow(ctx *context.APIContext) {
// responses:
// "204":
// "$ref": "#/responses/empty"
// "401":
// "$ref": "#/responses/unauthorized"
// "403":
// "$ref": "#/responses/forbidden"
// "404":
// "$ref": "#/responses/notFound"

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

@ -92,6 +92,10 @@ func ListMyGPGKeys(ctx *context.APIContext) {
// responses:
// "200":
// "$ref": "#/responses/GPGKeyList"
// "401":
// "$ref": "#/responses/unauthorized"
// "403":
// "$ref": "#/responses/forbidden"
listGPGKeys(ctx, ctx.Doer.ID, utils.GetListOptions(ctx))
}
@ -113,6 +117,10 @@ func GetGPGKey(ctx *context.APIContext) {
// responses:
// "200":
// "$ref": "#/responses/GPGKey"
// "401":
// "$ref": "#/responses/unauthorized"
// "403":
// "$ref": "#/responses/forbidden"
// "404":
// "$ref": "#/responses/notFound"
@ -164,6 +172,10 @@ func GetVerificationToken(ctx *context.APIContext) {
// responses:
// "200":
// "$ref": "#/responses/string"
// "401":
// "$ref": "#/responses/unauthorized"
// "403":
// "$ref": "#/responses/forbidden"
// "404":
// "$ref": "#/responses/notFound"
@ -183,6 +195,10 @@ func VerifyUserGPGKey(ctx *context.APIContext) {
// responses:
// "201":
// "$ref": "#/responses/GPGKey"
// "401":
// "$ref": "#/responses/unauthorized"
// "403":
// "$ref": "#/responses/forbidden"
// "404":
// "$ref": "#/responses/notFound"
// "422":
@ -244,6 +260,10 @@ func CreateGPGKey(ctx *context.APIContext) {
// responses:
// "201":
// "$ref": "#/responses/GPGKey"
// "401":
// "$ref": "#/responses/unauthorized"
// "403":
// "$ref": "#/responses/forbidden"
// "404":
// "$ref": "#/responses/notFound"
// "422":
@ -270,6 +290,8 @@ func DeleteGPGKey(ctx *context.APIContext) {
// responses:
// "204":
// "$ref": "#/responses/empty"
// "401":
// "$ref": "#/responses/unauthorized"
// "403":
// "$ref": "#/responses/forbidden"
// "404":

20
routers/api/v1/user/hook.go
View file

@ -32,6 +32,10 @@ func ListHooks(ctx *context.APIContext) {
// responses:
// "200":
// "$ref": "#/responses/HookList"
// "401":
// "$ref": "#/responses/unauthorized"
// "403":
// "$ref": "#/responses/forbidden"
utils.ListOwnerHooks(
ctx,
@ -56,6 +60,10 @@ func GetHook(ctx *context.APIContext) {
// responses:
// "200":
// "$ref": "#/responses/Hook"
// "401":
// "$ref": "#/responses/unauthorized"
// "403":
// "$ref": "#/responses/forbidden"
hook, err := utils.GetOwnerHook(ctx, ctx.Doer.ID, ctx.ParamsInt64("id"))
if err != nil {
@ -93,6 +101,10 @@ func CreateHook(ctx *context.APIContext) {
// responses:
// "201":
// "$ref": "#/responses/Hook"
// "401":
// "$ref": "#/responses/unauthorized"
// "403":
// "$ref": "#/responses/forbidden"
utils.AddOwnerHook(
ctx,
@ -124,6 +136,10 @@ func EditHook(ctx *context.APIContext) {
// responses:
// "200":
// "$ref": "#/responses/Hook"
// "401":
// "$ref": "#/responses/unauthorized"
// "403":
// "$ref": "#/responses/forbidden"
utils.EditOwnerHook(
ctx,
@ -150,6 +166,10 @@ func DeleteHook(ctx *context.APIContext) {
// responses:
// "204":
// "$ref": "#/responses/empty"
// "401":
// "$ref": "#/responses/unauthorized"
// "403":
// "$ref": "#/responses/forbidden"
utils.DeleteOwnerHook(
ctx,

14
routers/api/v1/user/key.go
View file

@ -121,6 +121,10 @@ func ListMyPublicKeys(ctx *context.APIContext) {
// responses:
// "200":
// "$ref": "#/responses/PublicKeyList"
// "401":
// "$ref": "#/responses/unauthorized"
// "403":
// "$ref": "#/responses/forbidden"
listPublicKeys(ctx, ctx.Doer)
}
@ -176,6 +180,10 @@ func GetPublicKey(ctx *context.APIContext) {
// responses:
// "200":
// "$ref": "#/responses/PublicKey"
// "401":
// "$ref": "#/responses/unauthorized"
// "403":
// "$ref": "#/responses/forbidden"
// "404":
// "$ref": "#/responses/notFound"
@ -240,6 +248,10 @@ func CreatePublicKey(ctx *context.APIContext) {
// responses:
// "201":
// "$ref": "#/responses/PublicKey"
// "401":
// "$ref": "#/responses/unauthorized"
// "403":
// "$ref": "#/responses/forbidden"
// "422":
// "$ref": "#/responses/validationError"
@ -264,6 +276,8 @@ func DeletePublicKey(ctx *context.APIContext) {
// responses:
// "204":
// "$ref": "#/responses/empty"
// "401":
// "$ref": "#/responses/unauthorized"
// "403":
// "$ref": "#/responses/forbidden"
// "404":

10
routers/api/v1/user/quota.go
View file

@ -18,6 +18,8 @@ func GetQuota(ctx *context.APIContext) {
// responses:
// "200":
// "$ref": "#/responses/QuotaInfo"
// "401":
// "$ref": "#/responses/unauthorized"
// "403":
// "$ref": "#/responses/forbidden"
@ -34,6 +36,8 @@ func CheckQuota(ctx *context.APIContext) {
// responses:
// "200":
// "$ref": "#/responses/boolean"
// "401":
// "$ref": "#/responses/unauthorized"
// "403":
// "$ref": "#/responses/forbidden"
// "422":
@ -61,6 +65,8 @@ func ListQuotaAttachments(ctx *context.APIContext) {
// responses:
// "200":
// "$ref": "#/responses/QuotaUsedAttachmentList"
// "401":
// "$ref": "#/responses/unauthorized"
// "403":
// "$ref": "#/responses/forbidden"
@ -86,6 +92,8 @@ func ListQuotaPackages(ctx *context.APIContext) {
// responses:
// "200":
// "$ref": "#/responses/QuotaUsedPackageList"
// "401":
// "$ref": "#/responses/unauthorized"
// "403":
// "$ref": "#/responses/forbidden"
@ -111,6 +119,8 @@ func ListQuotaArtifacts(ctx *context.APIContext) {
// responses:
// "200":
// "$ref": "#/responses/QuotaUsedArtifactList"
// "401":
// "$ref": "#/responses/unauthorized"
// "403":
// "$ref": "#/responses/forbidden"

4
routers/api/v1/user/repo.go
View file

@ -106,6 +106,10 @@ func ListMyRepos(ctx *context.APIContext) {
// responses:
// "200":
// "$ref": "#/responses/RepositoryList"
// "401":
// "$ref": "#/responses/unauthorized"
// "403":
// "$ref": "#/responses/forbidden"
// "422":
// "$ref": "#/responses/validationError"

4
routers/api/v1/user/runners.go
View file

@ -21,6 +21,10 @@ func GetRegistrationToken(ctx *context.APIContext) {
// responses:
// "200":
// "$ref": "#/responses/RegistrationToken"
// "401":
// "$ref": "#/responses/unauthorized"
// "403":
// "$ref": "#/responses/forbidden"
shared.GetRegistrationToken(ctx, ctx.Doer.ID, 0)
}

8
routers/api/v1/user/settings.go
View file

@ -24,6 +24,10 @@ func GetUserSettings(ctx *context.APIContext) {
// responses:
// "200":
// "$ref": "#/responses/UserSettings"
// "401":
// "$ref": "#/responses/unauthorized"
// "403":
// "$ref": "#/responses/forbidden"
ctx.JSON(http.StatusOK, convert.User2UserSettings(ctx.Doer))
}
@ -42,6 +46,10 @@ func UpdateUserSettings(ctx *context.APIContext) {
// responses:
// "200":
// "$ref": "#/responses/UserSettings"
// "401":
// "$ref": "#/responses/unauthorized"
// "403":
// "$ref": "#/responses/forbidden"
form := web.GetForm(ctx).(*api.UserSettingsOptions)

16
routers/api/v1/user/star.go
View file

@ -96,6 +96,10 @@ func GetMyStarredRepos(ctx *context.APIContext) {
// responses:
// "200":
// "$ref": "#/responses/RepositoryList"
// "401":
// "$ref": "#/responses/unauthorized"
// "403":
// "$ref": "#/responses/forbidden"
repos, err := getStarredRepos(ctx, ctx.Doer, true, utils.GetListOptions(ctx))
if err != nil {
@ -125,6 +129,10 @@ func IsStarring(ctx *context.APIContext) {
// responses:
// "204":
// "$ref": "#/responses/empty"
// "401":
// "$ref": "#/responses/unauthorized"
// "403":
// "$ref": "#/responses/forbidden"
// "404":
// "$ref": "#/responses/notFound"
@ -154,6 +162,10 @@ func Star(ctx *context.APIContext) {
// responses:
// "204":
// "$ref": "#/responses/empty"
// "401":
// "$ref": "#/responses/unauthorized"
// "403":
// "$ref": "#/responses/forbidden"
// "404":
// "$ref": "#/responses/notFound"
@ -185,6 +197,10 @@ func Unstar(ctx *context.APIContext) {
// responses:
// "204":
// "$ref": "#/responses/empty"
// "401":
// "$ref": "#/responses/unauthorized"
// "403":
// "$ref": "#/responses/forbidden"
// "404":
// "$ref": "#/responses/notFound"

16
routers/api/v1/user/user.go
View file

@ -137,6 +137,10 @@ func GetAuthenticatedUser(ctx *context.APIContext) {
// responses:
// "200":
// "$ref": "#/responses/User"
// "401":
// "$ref": "#/responses/unauthorized"
// "403":
// "$ref": "#/responses/forbidden"
ctx.JSON(http.StatusOK, convert.ToUser(ctx, ctx.Doer, ctx.Doer))
}
@ -244,6 +248,10 @@ func ListBlockedUsers(ctx *context.APIContext) {
// responses:
// "200":
// "$ref": "#/responses/BlockedUserList"
// "401":
// "$ref": "#/responses/unauthorized"
// "403":
// "$ref": "#/responses/forbidden"
utils.ListUserBlockedUsers(ctx, ctx.Doer)
}
@ -264,6 +272,10 @@ func BlockUser(ctx *context.APIContext) {
// responses:
// "204":
// "$ref": "#/responses/empty"
// "401":
// "$ref": "#/responses/unauthorized"
// "403":
// "$ref": "#/responses/forbidden"
// "404":
// "$ref": "#/responses/notFound"
// "422":
@ -293,6 +305,10 @@ func UnblockUser(ctx *context.APIContext) {
// responses:
// "204":
// "$ref": "#/responses/empty"
// "401":
// "$ref": "#/responses/unauthorized"
// "403":
// "$ref": "#/responses/forbidden"
// "404":
// "$ref": "#/responses/notFound"
// "422":

4
routers/api/v1/user/watch.go
View file

@ -91,6 +91,10 @@ func GetMyWatchedRepos(ctx *context.APIContext) {
// responses:
// "200":
// "$ref": "#/responses/RepositoryList"
// "401":
// "$ref": "#/responses/unauthorized"
// "403":
// "$ref": "#/responses/forbidden"
repos, total, err := getWatchedRepos(ctx, ctx.Doer, true, utils.GetListOptions(ctx))
if err != nil {