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 <earl-warren@noreply.codeberg.org>
Co-authored-by: 0ko <0ko@noreply.codeberg.org>
Co-committed-by: 0ko <0ko@noreply.codeberg.org>

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)

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:

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:

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:

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:

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:

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:

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:

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:

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:

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

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:

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:

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:

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:

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

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:

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": [
           {