From 022ab86988202ffcaed19000ccb9f751403b245c Mon Sep 17 00:00:00 2001 From: 0ko <0ko@noreply.codeberg.org> Date: Wed, 30 Jul 2025 18:08:28 +0200 Subject: [PATCH] chore(api): update swagger method descripitons (#8728) Speaking from personal experience, when exploring the API I find myself trying to parse the exact meaning of many descriptions for a while, and I also have to get used to many different kinds of inconsistencies and grammar issues. This PR improves a few of these. Some I tried to reword to make them easier to understand, for others I just improved consistency a little, like capitalization. This area needs more work, this PR just makes some progress. Anything that is improved in this one can be improved further in later PRs, so in review please focus on regressions if you find any. Reviewed-on: https://codeberg.org/forgejo/forgejo/pulls/8728 Reviewed-by: Earl Warren Co-authored-by: 0ko <0ko@noreply.codeberg.org> Co-committed-by: 0ko <0ko@noreply.codeberg.org> --- models/repo/topic.go | 2 +- routers/api/v1/admin/email.go | 4 +- routers/api/v1/admin/hooks.go | 4 +- routers/api/v1/admin/user.go | 14 ++--- routers/api/v1/org/action.go | 22 ++++---- routers/api/v1/org/avatar.go | 8 +-- routers/api/v1/org/org.go | 2 +- routers/api/v1/repo/avatar.go | 8 +-- routers/api/v1/repo/mirror.go | 8 +-- routers/api/v1/repo/pull_review.go | 4 +- routers/api/v1/repo/topic.go | 6 +-- routers/api/v1/user/app.go | 22 ++++---- routers/api/v1/user/avatar.go | 8 +-- routers/api/v1/user/email.go | 12 ++--- routers/api/v1/user/gpg_key.go | 8 +-- routers/api/v1/user/settings.go | 8 +-- routers/api/v1/user/user.go | 4 +- templates/swagger/v1_json.tmpl | 82 +++++++++++++++--------------- 18 files changed, 113 insertions(+), 113 deletions(-) diff --git a/models/repo/topic.go b/models/repo/topic.go index 4a3bdc7d8c..9086f17627 100644 --- a/models/repo/topic.go +++ b/models/repo/topic.go @@ -164,7 +164,7 @@ func FindTopics(ctx context.Context, opts *FindTopicOptions) ([]*Topic, int64, e orderBy := "topic.repo_count DESC" if opts.RepoID > 0 { sess.Join("INNER", "repo_topic", "repo_topic.topic_id = topic.id") - orderBy = "topic.name" // when render topics for a repo, it's better to sort them by name, to get consistent result + orderBy = "topic.name" // When rendering topics for a repo, it's better to sort them by name to get consistent results } if opts.PageSize > 0 { sess = db.SetSessionPagination(sess, opts) diff --git a/routers/api/v1/admin/email.go b/routers/api/v1/admin/email.go index 906780a44b..9f6ef0fedf 100644 --- a/routers/api/v1/admin/email.go +++ b/routers/api/v1/admin/email.go @@ -17,7 +17,7 @@ import ( func GetAllEmails(ctx *context.APIContext) { // swagger:operation GET /admin/emails admin adminGetAllEmails // --- - // summary: List all emails + // summary: List all users' email addresses // produces: // - application/json // parameters: @@ -60,7 +60,7 @@ func GetAllEmails(ctx *context.APIContext) { func SearchEmail(ctx *context.APIContext) { // swagger:operation GET /admin/emails/search admin adminSearchEmails // --- - // summary: Search all emails + // summary: Search users' email addresses // produces: // - application/json // parameters: diff --git a/routers/api/v1/admin/hooks.go b/routers/api/v1/admin/hooks.go index b3db2eb5e3..36ca6831e6 100644 --- a/routers/api/v1/admin/hooks.go +++ b/routers/api/v1/admin/hooks.go @@ -17,11 +17,11 @@ import ( webhook_service "forgejo.org/services/webhook" ) -// ListHooks list system's webhooks +// ListHooks list system webhooks func ListHooks(ctx *context.APIContext) { // swagger:operation GET /admin/hooks admin adminListHooks // --- - // summary: List system's webhooks + // summary: List global (system) webhooks // produces: // - application/json // parameters: diff --git a/routers/api/v1/admin/user.go b/routers/api/v1/admin/user.go index de54f21d94..f3e321a047 100644 --- a/routers/api/v1/admin/user.go +++ b/routers/api/v1/admin/user.go @@ -51,11 +51,11 @@ func parseAuthSource(ctx *context.APIContext, u *user_model.User, sourceID int64 u.LoginSource = source.ID } -// CreateUser create a user +// CreateUser create a user account func CreateUser(ctx *context.APIContext) { // swagger:operation POST /admin/users admin adminCreateUser // --- - // summary: Create a user + // summary: Create a user account // consumes: // - application/json // produces: @@ -274,7 +274,7 @@ func EditUser(ctx *context.APIContext) { func DeleteUser(ctx *context.APIContext) { // swagger:operation DELETE /admin/users/{username} admin adminDeleteUser // --- - // summary: Delete a user + // summary: Delete user account // produces: // - application/json // parameters: @@ -324,11 +324,11 @@ func DeleteUser(ctx *context.APIContext) { ctx.Status(http.StatusNoContent) } -// CreatePublicKey api for creating a public key to a user +// CreatePublicKey adds an SSH public key to user's account func CreatePublicKey(ctx *context.APIContext) { // swagger:operation POST /admin/users/{username}/keys admin adminCreatePublicKey // --- - // summary: Add a public key on behalf of a user + // summary: Add an SSH public key to user's account // consumes: // - application/json // produces: @@ -356,11 +356,11 @@ func CreatePublicKey(ctx *context.APIContext) { user.CreateUserPublicKey(ctx, *form, ctx.ContextUser.ID) } -// DeleteUserPublicKey api for deleting a user's public key +// DeleteUserPublicKey removes an SSH public key from user's account func DeleteUserPublicKey(ctx *context.APIContext) { // swagger:operation DELETE /admin/users/{username}/keys/{id} admin adminDeleteUserPublicKey // --- - // summary: Delete a user's public key + // summary: Remove a public key from user's account // produces: // - application/json // parameters: diff --git a/routers/api/v1/org/action.go b/routers/api/v1/org/action.go index 0d8550a019..8b330aa752 100644 --- a/routers/api/v1/org/action.go +++ b/routers/api/v1/org/action.go @@ -20,11 +20,11 @@ import ( secret_service "forgejo.org/services/secrets" ) -// ListActionsSecrets list an organization's actions secrets +// ListActionsSecrets lists actions secrets of an organization func (Action) ListActionsSecrets(ctx *context.APIContext) { // swagger:operation GET /orgs/{org}/actions/secrets organization orgListActionsSecrets // --- - // summary: List an organization's actions secrets + // summary: List actions secrets of an organization // produces: // - application/json // parameters: @@ -218,7 +218,7 @@ func (Action) SearchActionRunJobs(ctx *context.APIContext) { func (Action) ListVariables(ctx *context.APIContext) { // swagger:operation GET /orgs/{org}/actions/variables organization getOrgVariablesList // --- - // summary: Get an org-level variables list + // summary: List variables of an organization // produces: // - application/json // parameters: @@ -266,11 +266,11 @@ func (Action) ListVariables(ctx *context.APIContext) { ctx.JSON(http.StatusOK, variables) } -// GetVariable get an org-level variable +// GetVariable gives organization's variable func (Action) GetVariable(ctx *context.APIContext) { // swagger:operation GET /orgs/{org}/actions/variables/{variablename} organization getOrgVariable // --- - // summary: Get an org-level variable + // summary: Get organization's variable by name // produces: // - application/json // parameters: @@ -315,11 +315,11 @@ func (Action) GetVariable(ctx *context.APIContext) { ctx.JSON(http.StatusOK, variable) } -// DeleteVariable delete an org-level variable +// DeleteVariable deletes an organization's variable func (Action) DeleteVariable(ctx *context.APIContext) { // swagger:operation DELETE /orgs/{org}/actions/variables/{variablename} organization deleteOrgVariable // --- - // summary: Delete an org-level variable + // summary: Delete organization's variable by name // produces: // - application/json // parameters: @@ -359,11 +359,11 @@ func (Action) DeleteVariable(ctx *context.APIContext) { ctx.Status(http.StatusNoContent) } -// CreateVariable create an org-level variable +// CreateVariable creates a new variable in organization func (Action) CreateVariable(ctx *context.APIContext) { // swagger:operation POST /orgs/{org}/actions/variables/{variablename} organization createOrgVariable // --- - // summary: Create an org-level variable + // summary: Create a new variable in organization // consumes: // - application/json // produces: @@ -423,11 +423,11 @@ func (Action) CreateVariable(ctx *context.APIContext) { ctx.Status(http.StatusNoContent) } -// UpdateVariable update an org-level variable +// UpdateVariable updates variable in organization func (Action) UpdateVariable(ctx *context.APIContext) { // swagger:operation PUT /orgs/{org}/actions/variables/{variablename} organization updateOrgVariable // --- - // summary: Update an org-level variable + // summary: Update variable in organization // consumes: // - application/json // produces: diff --git a/routers/api/v1/org/avatar.go b/routers/api/v1/org/avatar.go index 824a9f3495..043da3186f 100644 --- a/routers/api/v1/org/avatar.go +++ b/routers/api/v1/org/avatar.go @@ -13,11 +13,11 @@ import ( user_service "forgejo.org/services/user" ) -// UpdateAvatarupdates the Avatar of an Organisation +// UpdateAvatar updates an organization's avatar func UpdateAvatar(ctx *context.APIContext) { // swagger:operation POST /orgs/{org}/avatar organization orgUpdateAvatar // --- - // summary: Update Avatar + // summary: Update an organization's avatar // produces: // - application/json // parameters: @@ -52,11 +52,11 @@ func UpdateAvatar(ctx *context.APIContext) { ctx.Status(http.StatusNoContent) } -// DeleteAvatar deletes the Avatar of an Organisation +// DeleteAvatar deletes an organization's avatar func DeleteAvatar(ctx *context.APIContext) { // swagger:operation DELETE /orgs/{org}/avatar organization orgDeleteAvatar // --- - // summary: Delete Avatar + // summary: Delete an organization's avatar. It will be replaced by a default one // produces: // - application/json // parameters: diff --git a/routers/api/v1/org/org.go b/routers/api/v1/org/org.go index 87bc27be63..a4ea924979 100644 --- a/routers/api/v1/org/org.go +++ b/routers/api/v1/org/org.go @@ -180,7 +180,7 @@ func GetUserOrgsPermissions(ctx *context.APIContext) { func GetAll(ctx *context.APIContext) { // swagger:operation Get /orgs organization orgGetAll // --- - // summary: Get list of organizations + // summary: List all organizations // produces: // - application/json // parameters: diff --git a/routers/api/v1/repo/avatar.go b/routers/api/v1/repo/avatar.go index 84aafe764d..12308ce2df 100644 --- a/routers/api/v1/repo/avatar.go +++ b/routers/api/v1/repo/avatar.go @@ -13,11 +13,11 @@ import ( repo_service "forgejo.org/services/repository" ) -// UpdateVatar updates the Avatar of an Repo +// UpdateVatar updates repo avatar func UpdateAvatar(ctx *context.APIContext) { // swagger:operation POST /repos/{owner}/{repo}/avatar repository repoUpdateAvatar // --- - // summary: Update avatar + // summary: Update a repository's avatar // produces: // - application/json // parameters: @@ -56,11 +56,11 @@ func UpdateAvatar(ctx *context.APIContext) { ctx.Status(http.StatusNoContent) } -// UpdateAvatar deletes the Avatar of an Repo +// DeleteAvatar deletes repo avatar func DeleteAvatar(ctx *context.APIContext) { // swagger:operation DELETE /repos/{owner}/{repo}/avatar repository repoDeleteAvatar // --- - // summary: Delete avatar + // summary: Delete a repository's avatar // produces: // - application/json // parameters: diff --git a/routers/api/v1/repo/mirror.go b/routers/api/v1/repo/mirror.go index f08867dee4..08ef68cbfc 100644 --- a/routers/api/v1/repo/mirror.go +++ b/routers/api/v1/repo/mirror.go @@ -251,11 +251,11 @@ func GetPushMirrorByName(ctx *context.APIContext) { ctx.JSON(http.StatusOK, m) } -// AddPushMirror adds a push mirror to a repository +// AddPushMirror sets up a new push mirror in a repository func AddPushMirror(ctx *context.APIContext) { // swagger:operation POST /repos/{owner}/{repo}/push_mirrors repository repoAddPushMirror // --- - // summary: add a push mirror to the repository + // summary: Set up a new push mirror in a repository // consumes: // - application/json // produces: @@ -296,11 +296,11 @@ func AddPushMirror(ctx *context.APIContext) { CreatePushMirror(ctx, pushMirror) } -// DeletePushMirrorByRemoteName deletes a push mirror from a repository by remoteName +// DeletePushMirrorByRemoteName removes a push mirror from a repository by remoteName func DeletePushMirrorByRemoteName(ctx *context.APIContext) { // swagger:operation DELETE /repos/{owner}/{repo}/push_mirrors/{name} repository repoDeletePushMirror // --- - // summary: deletes a push mirror from a repository by remoteName + // summary: Remove a push mirror from a repository by remoteName // produces: // - application/json // parameters: diff --git a/routers/api/v1/repo/pull_review.go b/routers/api/v1/repo/pull_review.go index 830a62bf54..06b47fef70 100644 --- a/routers/api/v1/repo/pull_review.go +++ b/routers/api/v1/repo/pull_review.go @@ -716,7 +716,7 @@ func prepareSingleReview(ctx *context.APIContext) (*issues_model.Review, *issues func CreateReviewRequests(ctx *context.APIContext) { // swagger:operation POST /repos/{owner}/{repo}/pulls/{index}/requested_reviewers repository repoCreatePullReviewRequests // --- - // summary: create review requests for a pull request + // summary: Create review requests for a pull request // produces: // - application/json // parameters: @@ -757,7 +757,7 @@ func CreateReviewRequests(ctx *context.APIContext) { func DeleteReviewRequests(ctx *context.APIContext) { // swagger:operation DELETE /repos/{owner}/{repo}/pulls/{index}/requested_reviewers repository repoDeletePullReviewRequests // --- - // summary: cancel review requests for a pull request + // summary: Cancel review requests for a pull request // produces: // - application/json // parameters: diff --git a/routers/api/v1/repo/topic.go b/routers/api/v1/repo/topic.go index daa637936e..8829e37bc3 100644 --- a/routers/api/v1/repo/topic.go +++ b/routers/api/v1/repo/topic.go @@ -253,17 +253,17 @@ func DeleteTopic(ctx *context.APIContext) { ctx.Status(http.StatusNoContent) } -// TopicSearch search for creating topic +// TopicSearch searches known topics, i.e. when adding a topic to a repository func TopicSearch(ctx *context.APIContext) { // swagger:operation GET /topics/search repository topicSearch // --- - // summary: search topics via keyword + // summary: Search for topics by keyword // produces: // - application/json // parameters: // - name: q // in: query - // description: keywords to search + // description: keyword to search for // required: true // type: string // - name: page diff --git a/routers/api/v1/user/app.go b/routers/api/v1/user/app.go index 138ad5a1d2..65955913fd 100644 --- a/routers/api/v1/user/app.go +++ b/routers/api/v1/user/app.go @@ -71,11 +71,11 @@ func ListAccessTokens(ctx *context.APIContext) { ctx.JSON(http.StatusOK, &apiTokens) } -// CreateAccessToken create access tokens +// CreateAccessToken creates an access token for doer func CreateAccessToken(ctx *context.APIContext) { // swagger:operation POST /users/{username}/tokens user userCreateToken // --- - // summary: Create an access token + // summary: Generate an access token for the current user // consumes: // - application/json // produces: @@ -141,11 +141,11 @@ func CreateAccessToken(ctx *context.APIContext) { }) } -// DeleteAccessToken delete access tokens +// DeleteAccessToken deletes an access token from doer's account func DeleteAccessToken(ctx *context.APIContext) { // swagger:operation DELETE /users/{username}/tokens/{token} user userDeleteAccessToken // --- - // summary: delete an access token + // summary: Delete an access token from current user's account // produces: // - application/json // parameters: @@ -214,7 +214,7 @@ func DeleteAccessToken(ctx *context.APIContext) { func CreateOauth2Application(ctx *context.APIContext) { // swagger:operation POST /user/applications/oauth2 user userCreateOAuth2Application // --- - // summary: creates a new OAuth2 application + // summary: Creates a new OAuth2 application // produces: // - application/json // parameters: @@ -298,11 +298,11 @@ func ListOauth2Applications(ctx *context.APIContext) { ctx.JSON(http.StatusOK, &apiApps) } -// DeleteOauth2Application delete OAuth2 Application +// DeleteOauth2Application delete OAuth2 application func DeleteOauth2Application(ctx *context.APIContext) { // swagger:operation DELETE /user/applications/oauth2/{id} user userDeleteOAuth2Application // --- - // summary: delete an OAuth2 Application + // summary: Delete an OAuth2 application // produces: // - application/json // parameters: @@ -334,11 +334,11 @@ func DeleteOauth2Application(ctx *context.APIContext) { ctx.Status(http.StatusNoContent) } -// GetOauth2Application get OAuth2 Application +// GetOauth2Application returns an OAuth2 application func GetOauth2Application(ctx *context.APIContext) { // swagger:operation GET /user/applications/oauth2/{id} user userGetOAuth2Application // --- - // summary: get an OAuth2 Application + // summary: Get an OAuth2 application // produces: // - application/json // parameters: @@ -377,11 +377,11 @@ func GetOauth2Application(ctx *context.APIContext) { ctx.JSON(http.StatusOK, convert.ToOAuth2Application(app)) } -// UpdateOauth2Application update OAuth2 Application +// UpdateOauth2Application updates an OAuth2 application func UpdateOauth2Application(ctx *context.APIContext) { // swagger:operation PATCH /user/applications/oauth2/{id} user userUpdateOAuth2Application // --- - // summary: update an OAuth2 Application, this includes regenerating the client secret + // summary: Update an OAuth2 application, this includes regenerating the client secret // produces: // - application/json // parameters: diff --git a/routers/api/v1/user/avatar.go b/routers/api/v1/user/avatar.go index 453682a37b..2b0659c251 100644 --- a/routers/api/v1/user/avatar.go +++ b/routers/api/v1/user/avatar.go @@ -13,11 +13,11 @@ import ( user_service "forgejo.org/services/user" ) -// UpdateAvatar updates the Avatar of an User +// UpdateAvatar updates doer's avatar func UpdateAvatar(ctx *context.APIContext) { // swagger:operation POST /user/avatar user userUpdateAvatar // --- - // summary: Update Avatar + // summary: Update avatar of the current user // produces: // - application/json // parameters: @@ -49,11 +49,11 @@ func UpdateAvatar(ctx *context.APIContext) { ctx.Status(http.StatusNoContent) } -// DeleteAvatar deletes the Avatar of an User +// DeleteAvatar deletes doer's avatar func DeleteAvatar(ctx *context.APIContext) { // swagger:operation DELETE /user/avatar user userDeleteAvatar // --- - // summary: Delete Avatar + // summary: Delete avatar of the current user. It will be replaced by a default one // produces: // - application/json // responses: diff --git a/routers/api/v1/user/email.go b/routers/api/v1/user/email.go index 03d8d14b90..38da23442d 100644 --- a/routers/api/v1/user/email.go +++ b/routers/api/v1/user/email.go @@ -16,12 +16,12 @@ import ( user_service "forgejo.org/services/user" ) -// ListEmails list all of the authenticated user's email addresses +// ListEmails lists doer's all email addresses // see https://github.com/gogits/go-gogs-client/wiki/Users-Emails#list-email-addresses-for-a-user func ListEmails(ctx *context.APIContext) { // swagger:operation GET /user/emails user userListEmails // --- - // summary: List the authenticated user's email addresses + // summary: List all email addresses of the current user // produces: // - application/json // responses: @@ -44,11 +44,11 @@ func ListEmails(ctx *context.APIContext) { ctx.JSON(http.StatusOK, &apiEmails) } -// AddEmail add an email address +// AddEmail adds an email address to doer's account func AddEmail(ctx *context.APIContext) { // swagger:operation POST /user/emails user userAddEmail // --- - // summary: Add email addresses + // summary: Add an email addresses to the current user's account // produces: // - application/json // parameters: @@ -102,11 +102,11 @@ func AddEmail(ctx *context.APIContext) { ctx.JSON(http.StatusCreated, apiEmails) } -// DeleteEmail delete email +// DeleteEmail deletes an email address from doer's account func DeleteEmail(ctx *context.APIContext) { // swagger:operation DELETE /user/emails user userDeleteEmail // --- - // summary: Delete email addresses + // summary: Delete email addresses from the current user's account // produces: // - application/json // parameters: diff --git a/routers/api/v1/user/gpg_key.go b/routers/api/v1/user/gpg_key.go index 886e33b205..bb7f3d3522 100644 --- a/routers/api/v1/user/gpg_key.go +++ b/routers/api/v1/user/gpg_key.go @@ -249,11 +249,11 @@ type swaggerUserCurrentPostGPGKey struct { Form api.CreateGPGKeyOption } -// CreateGPGKey create a GPG key belonging to the authenticated user +// CreateGPGKey adds a GPG public key doer's account func CreateGPGKey(ctx *context.APIContext) { // swagger:operation POST /user/gpg_keys user userCurrentPostGPGKey // --- - // summary: Create a GPG key + // summary: Add a GPG public key to current user's account // consumes: // - application/json // produces: @@ -274,11 +274,11 @@ func CreateGPGKey(ctx *context.APIContext) { CreateUserGPGKey(ctx, *form, ctx.Doer.ID) } -// DeleteGPGKey remove a GPG key belonging to the authenticated user +// DeleteGPGKey removes a GPG public key from doer's account func DeleteGPGKey(ctx *context.APIContext) { // swagger:operation DELETE /user/gpg_keys/{id} user userCurrentDeleteGPGKey // --- - // summary: Remove a GPG key + // summary: Remove a GPG public key from current user's account // produces: // - application/json // parameters: diff --git a/routers/api/v1/user/settings.go b/routers/api/v1/user/settings.go index 134b448718..53455bcd75 100644 --- a/routers/api/v1/user/settings.go +++ b/routers/api/v1/user/settings.go @@ -14,11 +14,11 @@ import ( user_service "forgejo.org/services/user" ) -// GetUserSettings returns user settings +// GetUserSettings returns doer's account settings func GetUserSettings(ctx *context.APIContext) { // swagger:operation GET /user/settings user getUserSettings // --- - // summary: Get user settings + // summary: Get current user's account settings // produces: // - application/json // responses: @@ -31,11 +31,11 @@ func GetUserSettings(ctx *context.APIContext) { ctx.JSON(http.StatusOK, convert.User2UserSettings(ctx.Doer)) } -// UpdateUserSettings returns user settings +// UpdateUserSettings updates settings in doer's account func UpdateUserSettings(ctx *context.APIContext) { // swagger:operation PATCH /user/settings user updateUserSettings // --- - // summary: Update user settings + // summary: Update settings in current user's account // parameters: // - name: body // in: body diff --git a/routers/api/v1/user/user.go b/routers/api/v1/user/user.go index 19f7440047..2bd2829d09 100644 --- a/routers/api/v1/user/user.go +++ b/routers/api/v1/user/user.go @@ -266,7 +266,7 @@ func ListBlockedUsers(ctx *context.APIContext) { func BlockUser(ctx *context.APIContext) { // swagger:operation PUT /user/block/{username} user userBlockUser // --- - // summary: Blocks a user from the doer. + // summary: Blocks a user from the doer // produces: // - application/json // parameters: @@ -299,7 +299,7 @@ func BlockUser(ctx *context.APIContext) { func UnblockUser(ctx *context.APIContext) { // swagger:operation PUT /user/unblock/{username} user userUnblockUser // --- - // summary: Unblocks a user from the doer. + // summary: Unblocks a user from the doer // produces: // - application/json // parameters: diff --git a/templates/swagger/v1_json.tmpl b/templates/swagger/v1_json.tmpl index e03f5d57c1..a610620eab 100644 --- a/templates/swagger/v1_json.tmpl +++ b/templates/swagger/v1_json.tmpl @@ -239,7 +239,7 @@ "tags": [ "admin" ], - "summary": "List all emails", + "summary": "List all users' email addresses", "operationId": "adminGetAllEmails", "parameters": [ { @@ -273,7 +273,7 @@ "tags": [ "admin" ], - "summary": "Search all emails", + "summary": "Search users' email addresses", "operationId": "adminSearchEmails", "parameters": [ { @@ -313,7 +313,7 @@ "tags": [ "admin" ], - "summary": "List system's webhooks", + "summary": "List global (system) webhooks", "operationId": "adminListHooks", "parameters": [ { @@ -1220,7 +1220,7 @@ "tags": [ "admin" ], - "summary": "Create a user", + "summary": "Create a user account", "operationId": "adminCreateUser", "parameters": [ { @@ -1255,7 +1255,7 @@ "tags": [ "admin" ], - "summary": "Delete a user", + "summary": "Delete user account", "operationId": "adminDeleteUser", "parameters": [ { @@ -1342,7 +1342,7 @@ "tags": [ "admin" ], - "summary": "Add a public key on behalf of a user", + "summary": "Add an SSH public key to user's account", "operationId": "adminCreatePublicKey", "parameters": [ { @@ -1381,7 +1381,7 @@ "tags": [ "admin" ], - "summary": "Delete a user's public key", + "summary": "Remove a public key from user's account", "operationId": "adminDeleteUserPublicKey", "parameters": [ { @@ -2158,7 +2158,7 @@ "tags": [ "organization" ], - "summary": "Get list of organizations", + "summary": "List all organizations", "operationId": "orgGetAll", "parameters": [ { @@ -2381,7 +2381,7 @@ "tags": [ "organization" ], - "summary": "List an organization's actions secrets", + "summary": "List actions secrets of an organization", "operationId": "orgListActionsSecrets", "parameters": [ { @@ -2514,7 +2514,7 @@ "tags": [ "organization" ], - "summary": "Get an org-level variables list", + "summary": "List variables of an organization", "operationId": "getOrgVariablesList", "parameters": [ { @@ -2558,7 +2558,7 @@ "tags": [ "organization" ], - "summary": "Get an org-level variable", + "summary": "Get organization's variable by name", "operationId": "getOrgVariable", "parameters": [ { @@ -2598,7 +2598,7 @@ "tags": [ "organization" ], - "summary": "Update an org-level variable", + "summary": "Update variable in organization", "operationId": "updateOrgVariable", "parameters": [ { @@ -2648,7 +2648,7 @@ "tags": [ "organization" ], - "summary": "Create an org-level variable", + "summary": "Create a new variable in organization", "operationId": "createOrgVariable", "parameters": [ { @@ -2695,7 +2695,7 @@ "tags": [ "organization" ], - "summary": "Delete an org-level variable", + "summary": "Delete organization's variable by name", "operationId": "deleteOrgVariable", "parameters": [ { @@ -2788,7 +2788,7 @@ "tags": [ "organization" ], - "summary": "Update Avatar", + "summary": "Update an organization's avatar", "operationId": "orgUpdateAvatar", "parameters": [ { @@ -2822,7 +2822,7 @@ "tags": [ "organization" ], - "summary": "Delete Avatar", + "summary": "Delete an organization's avatar. It will be replaced by a default one", "operationId": "orgDeleteAvatar", "parameters": [ { @@ -5730,7 +5730,7 @@ "tags": [ "repository" ], - "summary": "Update avatar", + "summary": "Update a repository's avatar", "operationId": "repoUpdateAvatar", "parameters": [ { @@ -5771,7 +5771,7 @@ "tags": [ "repository" ], - "summary": "Delete avatar", + "summary": "Delete a repository's avatar", "operationId": "repoDeleteAvatar", "parameters": [ { @@ -13690,7 +13690,7 @@ "tags": [ "repository" ], - "summary": "create review requests for a pull request", + "summary": "Create review requests for a pull request", "operationId": "repoCreatePullReviewRequests", "parameters": [ { @@ -13743,7 +13743,7 @@ "tags": [ "repository" ], - "summary": "cancel review requests for a pull request", + "summary": "Cancel review requests for a pull request", "operationId": "repoDeletePullReviewRequests", "parameters": [ { @@ -14558,7 +14558,7 @@ "tags": [ "repository" ], - "summary": "add a push mirror to the repository", + "summary": "Set up a new push mirror in a repository", "operationId": "repoAddPushMirror", "parameters": [ { @@ -14702,7 +14702,7 @@ "tags": [ "repository" ], - "summary": "deletes a push mirror from a repository by remoteName", + "summary": "Remove a push mirror from a repository by remoteName", "operationId": "repoDeletePushMirror", "parameters": [ { @@ -18026,12 +18026,12 @@ "tags": [ "repository" ], - "summary": "search topics via keyword", + "summary": "Search for topics by keyword", "operationId": "topicSearch", "parameters": [ { "type": "string", - "description": "keywords to search", + "description": "keyword to search for", "name": "q", "in": "query", "required": true @@ -18490,7 +18490,7 @@ "tags": [ "user" ], - "summary": "creates a new OAuth2 application", + "summary": "Creates a new OAuth2 application", "operationId": "userCreateOAuth2Application", "parameters": [ { @@ -18526,7 +18526,7 @@ "tags": [ "user" ], - "summary": "get an OAuth2 Application", + "summary": "Get an OAuth2 application", "operationId": "userGetOAuth2Application", "parameters": [ { @@ -18560,7 +18560,7 @@ "tags": [ "user" ], - "summary": "delete an OAuth2 Application", + "summary": "Delete an OAuth2 application", "operationId": "userDeleteOAuth2Application", "parameters": [ { @@ -18594,7 +18594,7 @@ "tags": [ "user" ], - "summary": "update an OAuth2 Application, this includes regenerating the client secret", + "summary": "Update an OAuth2 application, this includes regenerating the client secret", "operationId": "userUpdateOAuth2Application", "parameters": [ { @@ -18638,7 +18638,7 @@ "tags": [ "user" ], - "summary": "Update Avatar", + "summary": "Update avatar of the current user", "operationId": "userUpdateAvatar", "parameters": [ { @@ -18668,7 +18668,7 @@ "tags": [ "user" ], - "summary": "Delete Avatar", + "summary": "Delete avatar of the current user. It will be replaced by a default one", "operationId": "userDeleteAvatar", "responses": { "204": { @@ -18691,7 +18691,7 @@ "tags": [ "user" ], - "summary": "Blocks a user from the doer.", + "summary": "Blocks a user from the doer", "operationId": "userBlockUser", "parameters": [ { @@ -18729,7 +18729,7 @@ "tags": [ "user" ], - "summary": "List the authenticated user's email addresses", + "summary": "List all email addresses of the current user", "operationId": "userListEmails", "responses": { "200": { @@ -18750,7 +18750,7 @@ "tags": [ "user" ], - "summary": "Add email addresses", + "summary": "Add an email addresses to the current user's account", "operationId": "userAddEmail", "parameters": [ { @@ -18783,7 +18783,7 @@ "tags": [ "user" ], - "summary": "Delete email addresses", + "summary": "Delete email addresses from the current user's account", "operationId": "userDeleteEmail", "parameters": [ { @@ -19080,7 +19080,7 @@ "tags": [ "user" ], - "summary": "Create a GPG key", + "summary": "Add a GPG public key to current user's account", "operationId": "userCurrentPostGPGKey", "parameters": [ { @@ -19152,7 +19152,7 @@ "tags": [ "user" ], - "summary": "Remove a GPG key", + "summary": "Remove a GPG public key from current user's account", "operationId": "userCurrentDeleteGPGKey", "parameters": [ { @@ -19862,7 +19862,7 @@ "tags": [ "user" ], - "summary": "Get user settings", + "summary": "Get current user's account settings", "operationId": "getUserSettings", "responses": { "200": { @@ -19883,7 +19883,7 @@ "tags": [ "user" ], - "summary": "Update user settings", + "summary": "Update settings in current user's account", "operationId": "updateUserSettings", "parameters": [ { @@ -20230,7 +20230,7 @@ "tags": [ "user" ], - "summary": "Unblocks a user from the doer.", + "summary": "Unblocks a user from the doer", "operationId": "userUnblockUser", "parameters": [ { @@ -20903,7 +20903,7 @@ "tags": [ "user" ], - "summary": "Create an access token", + "summary": "Generate an access token for the current user", "operationId": "userCreateToken", "parameters": [ { @@ -20945,7 +20945,7 @@ "tags": [ "user" ], - "summary": "delete an access token", + "summary": "Delete an access token from current user's account", "operationId": "userDeleteAccessToken", "parameters": [ {