Add a login/login-name/username disambiguation to affected endpoint parameters and response/request models (#34901)

Issue: [link](https://github.com/go-gitea/gitea/issues/9637)

Changes introduced: I have clarified the problematic terms (`login`,
`login_name`, and `username`) in all affected endpoints.

The changes were made to relevant:
- HTTP endpoint parameters' descriptions 
- response/request models' fields

modules/structs/admin_user.go

@@ -8,8 +8,11 @@ import "time"
 
 // CreateUserOption create user options
 type CreateUserOption struct {
-	SourceID  int64  `json:"source_id"`
+	SourceID int64 `json:"source_id"`
+	// identifier of the user, provided by the external authenticator (if configured)
+	// default: empty
 	LoginName string `json:"login_name"`
+	// username of the user
 	// required: true
 	Username string `json:"username" binding:"Required;Username;MaxSize(40)"`
 	FullName string `json:"full_name" binding:"MaxSize(100)"`
@@ -32,6 +35,8 @@ type CreateUserOption struct {
 type EditUserOption struct {
 	// required: true
 	SourceID int64 `json:"source_id"`
+	// identifier of the user, provided by the external authenticator (if configured)
+	// default: empty
 	// required: true
 	LoginName string `json:"login_name" binding:"Required"`
 	// swagger:strfmt email

modules/structs/hook.go

@@ -71,7 +71,8 @@ type PayloadUser struct {
 	// Full name of the commit author
 	Name string `json:"name"`
 	// swagger:strfmt email
-	Email    string `json:"email"`
+	Email string `json:"email"`
+	// username of the user
 	UserName string `json:"username"`
 }
 

modules/structs/issue_tracked_time.go

@@ -14,7 +14,7 @@ type AddTimeOption struct {
 	Time int64 `json:"time" binding:"Required"`
 	// swagger:strfmt date-time
 	Created time.Time `json:"created"`
-	// User who spent the time (optional)
+	// username of the user who spent the time working on the issue (optional)
 	User string `json:"user_name"`
 }
 
@@ -26,7 +26,8 @@ type TrackedTime struct {
 	// Time in seconds
 	Time int64 `json:"time"`
 	// deprecated (only for backwards compatibility)
-	UserID   int64  `json:"user_id"`
+	UserID int64 `json:"user_id"`
+	// username of the user
 	UserName string `json:"user_name"`
 	// deprecated (only for backwards compatibility)
 	IssueID int64  `json:"issue_id"`

modules/structs/org.go

@@ -15,6 +15,7 @@ type Organization struct {
 	Location                  string `json:"location"`
 	Visibility                string `json:"visibility"`
 	RepoAdminChangeTeamAccess bool   `json:"repo_admin_change_team_access"`
+	// username of the organization
 	// deprecated
 	UserName string `json:"username"`
 }
@@ -30,6 +31,7 @@ type OrganizationPermissions struct {
 
 // CreateOrgOption options for creating an organization
 type CreateOrgOption struct {
+	// username of the organization
 	// required: true
 	UserName    string `json:"username" binding:"Required;Username;MaxSize(40)"`
 	FullName    string `json:"full_name" binding:"MaxSize(100)"`

modules/structs/user.go

@@ -15,9 +15,9 @@ import (
 type User struct {
 	// the user's id
 	ID int64 `json:"id"`
-	// the user's username
+	// login of the user, same as `username`
 	UserName string `json:"login"`
-	// the user's authentication sign-in name.
+	// identifier of the user, provided by the external authenticator (if configured)
 	// default: empty
 	LoginName string `json:"login_name"`
 	// The ID of the user's Authentication Source

modules/structs/user_email.go

@@ -11,6 +11,7 @@ type Email struct {
 	Verified bool   `json:"verified"`
 	Primary  bool   `json:"primary"`
 	UserID   int64  `json:"user_id"`
+	// username of the user
 	UserName string `json:"username"`
 }
 

routers/api/v1/admin/org.go

@@ -29,7 +29,7 @@ func CreateOrg(ctx *context.APIContext) {
 	// parameters:
 	// - name: username
 	//   in: path
-	//   description: username of the user that will own the created organization
+	//   description: username of the user who will own the created organization
 	//   type: string
 	//   required: true
 	// - name: organization

routers/api/v1/admin/repo.go

@@ -22,7 +22,7 @@ func CreateRepo(ctx *context.APIContext) {
 	// parameters:
 	// - name: username
 	//   in: path
-	//   description: username of the user. This user will own the created repository
+	//   description: username of the user who will own the created repository
 	//   type: string
 	//   required: true
 	// - name: repository

routers/api/v1/admin/user.go

@@ -175,7 +175,7 @@ func EditUser(ctx *context.APIContext) {
 	// parameters:
 	// - name: username
 	//   in: path
-	//   description: username of user to edit
+	//   description: username of the user whose data is to be edited
 	//   type: string
 	//   required: true
 	// - name: body
@@ -272,7 +272,7 @@ func DeleteUser(ctx *context.APIContext) {
 	// parameters:
 	// - name: username
 	//   in: path
-	//   description: username of user to delete
+	//   description: username of the user to delete
 	//   type: string
 	//   required: true
 	// - name: purge
@@ -328,7 +328,7 @@ func CreatePublicKey(ctx *context.APIContext) {
 	// parameters:
 	// - name: username
 	//   in: path
-	//   description: username of the user
+	//   description: username of the user who is to receive a public key
 	//   type: string
 	//   required: true
 	// - name: key
@@ -358,7 +358,7 @@ func DeleteUserPublicKey(ctx *context.APIContext) {
 	// parameters:
 	// - name: username
 	//   in: path
-	//   description: username of user
+	//   description: username of the user whose public key is to be deleted
 	//   type: string
 	//   required: true
 	// - name: id
@@ -405,7 +405,7 @@ func SearchUsers(ctx *context.APIContext) {
 	//   format: int64
 	// - name: login_name
 	//   in: query
-	//   description: user's login name to search for
+	//   description: identifier of the user, provided by the external authenticator
 	//   type: string
 	// - name: page
 	//   in: query
@@ -456,7 +456,7 @@ func RenameUser(ctx *context.APIContext) {
 	// parameters:
 	// - name: username
 	//   in: path
-	//   description: existing username of user
+	//   description: current username of the user
 	//   type: string
 	//   required: true
 	// - name: body

routers/api/v1/admin/user_badge.go

@@ -22,7 +22,7 @@ func ListUserBadges(ctx *context.APIContext) {
 	// parameters:
 	// - name: username
 	//   in: path
-	//   description: username of user
+	//   description: username of the user whose badges are to be listed
 	//   type: string
 	//   required: true
 	// responses:
@@ -53,7 +53,7 @@ func AddUserBadges(ctx *context.APIContext) {
 	// parameters:
 	// - name: username
 	//   in: path
-	//   description: username of user
+	//   description: username of the user to whom a badge is to be added
 	//   type: string
 	//   required: true
 	// - name: body
@@ -87,7 +87,7 @@ func DeleteUserBadges(ctx *context.APIContext) {
 	// parameters:
 	// - name: username
 	//   in: path
-	//   description: username of user
+	//   description: username of the user whose badge is to be deleted
 	//   type: string
 	//   required: true
 	// - name: body

routers/api/v1/org/block.go

@@ -47,7 +47,7 @@ func CheckUserBlock(ctx *context.APIContext) {
 	//   required: true
 	// - name: username
 	//   in: path
-	//   description: user to check
+	//   description: username of the user to check
 	//   type: string
 	//   required: true
 	// responses:
@@ -71,7 +71,7 @@ func BlockUser(ctx *context.APIContext) {
 	//   required: true
 	// - name: username
 	//   in: path
-	//   description: user to block
+	//   description: username of the user to block
 	//   type: string
 	//   required: true
 	// - name: note
@@ -101,7 +101,7 @@ func UnblockUser(ctx *context.APIContext) {
 	//   required: true
 	// - name: username
 	//   in: path
-	//   description: user to unblock
+	//   description: username of the user to unblock
 	//   type: string
 	//   required: true
 	// responses:

routers/api/v1/org/member.go

@@ -133,7 +133,7 @@ func IsMember(ctx *context.APIContext) {
 	//   required: true
 	// - name: username
 	//   in: path
-	//   description: username of the user
+	//   description: username of the user to check for an organization membership
 	//   type: string
 	//   required: true
 	// responses:
@@ -186,7 +186,7 @@ func IsPublicMember(ctx *context.APIContext) {
 	//   required: true
 	// - name: username
 	//   in: path
-	//   description: username of the user
+	//   description: username of the user to check for a public organization membership
 	//   type: string
 	//   required: true
 	// responses:
@@ -240,7 +240,7 @@ func PublicizeMember(ctx *context.APIContext) {
 	//   required: true
 	// - name: username
 	//   in: path
-	//   description: username of the user
+	//   description: username of the user whose membership is to be publicized
 	//   type: string
 	//   required: true
 	// responses:
@@ -282,7 +282,7 @@ func ConcealMember(ctx *context.APIContext) {
 	//   required: true
 	// - name: username
 	//   in: path
-	//   description: username of the user
+	//   description: username of the user whose membership is to be concealed
 	//   type: string
 	//   required: true
 	// responses:
@@ -324,7 +324,7 @@ func DeleteMember(ctx *context.APIContext) {
 	//   required: true
 	// - name: username
 	//   in: path
-	//   description: username of the user
+	//   description: username of the user to remove from the organization
 	//   type: string
 	//   required: true
 	// responses:

routers/api/v1/org/org.go

@@ -82,7 +82,7 @@ func ListUserOrgs(ctx *context.APIContext) {
 	// parameters:
 	// - name: username
 	//   in: path
-	//   description: username of user
+	//   description: username of the user whose organizations are to be listed
 	//   type: string
 	//   required: true
 	// - name: page
@@ -112,7 +112,7 @@ func GetUserOrgsPermissions(ctx *context.APIContext) {
 	// parameters:
 	// - name: username
 	//   in: path
-	//   description: username of user
+	//   description: username of the user whose permissions are to be obtained
 	//   type: string
 	//   required: true
 	// - name: org

routers/api/v1/org/team.go

@@ -426,7 +426,7 @@ func GetTeamMember(ctx *context.APIContext) {
 	//   required: true
 	// - name: username
 	//   in: path
-	//   description: username of the member to list
+	//   description: username of the user whose data is to be listed
 	//   type: string
 	//   required: true
 	// responses:
@@ -467,7 +467,7 @@ func AddTeamMember(ctx *context.APIContext) {
 	//   required: true
 	// - name: username
 	//   in: path
-	//   description: username of the user to add
+	//   description: username of the user to add to a team
 	//   type: string
 	//   required: true
 	// responses:
@@ -509,7 +509,7 @@ func RemoveTeamMember(ctx *context.APIContext) {
 	//   required: true
 	// - name: username
 	//   in: path
-	//   description: username of the user to remove
+	//   description: username of the user to remove from a team
 	//   type: string
 	//   required: true
 	// responses:

routers/api/v1/repo/collaborators.go

@@ -93,7 +93,7 @@ func IsCollaborator(ctx *context.APIContext) {
 	//   required: true
 	// - name: collaborator
 	//   in: path
-	//   description: username of the collaborator
+	//   description: username of the user to check for being a collaborator
 	//   type: string
 	//   required: true
 	// responses:
@@ -145,7 +145,7 @@ func AddOrUpdateCollaborator(ctx *context.APIContext) {
 	//   required: true
 	// - name: collaborator
 	//   in: path
-	//   description: username of the collaborator to add
+	//   description: username of the user to add or update as a collaborator
 	//   type: string
 	//   required: true
 	// - name: body
@@ -264,7 +264,7 @@ func GetRepoPermissions(ctx *context.APIContext) {
 	//   required: true
 	// - name: collaborator
 	//   in: path
-	//   description: username of the collaborator
+	//   description: username of the collaborator whose permissions are to be obtained
 	//   type: string
 	//   required: true
 	// responses:

routers/api/v1/repo/issue_subscription.go

@@ -43,7 +43,7 @@ func AddIssueSubscription(ctx *context.APIContext) {
 	//   required: true
 	// - name: user
 	//   in: path
-	//   description: user to subscribe
+	//   description: username of the user to subscribe the issue to
 	//   type: string
 	//   required: true
 	// responses:
@@ -87,7 +87,7 @@ func DelIssueSubscription(ctx *context.APIContext) {
 	//   required: true
 	// - name: user
 	//   in: path
-	//   description: user witch unsubscribe
+	//   description: username of the user to unsubscribe from an issue
 	//   type: string
 	//   required: true
 	// responses:

routers/api/v1/repo/issue_tracked_time.go

@@ -405,7 +405,7 @@ func ListTrackedTimesByUser(ctx *context.APIContext) {
 	//   required: true
 	// - name: user
 	//   in: path
-	//   description: username of user
+	//   description: username of the user whose tracked times are to be listed
 	//   type: string
 	//   required: true
 	// responses:

routers/api/v1/user/app.go

@@ -30,7 +30,7 @@ func ListAccessTokens(ctx *context.APIContext) {
 	// parameters:
 	// - name: username
 	//   in: path
-	//   description: username of user
+	//   description: username of to user whose access tokens are to be listed
 	//   type: string
 	//   required: true
 	// - name: page
@@ -83,7 +83,7 @@ func CreateAccessToken(ctx *context.APIContext) {
 	// parameters:
 	// - name: username
 	//   in: path
-	//   description: username of user
+	//   description: username of the user whose token is to be created
 	//   required: true
 	//   type: string
 	// - name: body
@@ -149,7 +149,7 @@ func DeleteAccessToken(ctx *context.APIContext) {
 	// parameters:
 	// - name: username
 	//   in: path
-	//   description: username of user
+	//   description: username of the user whose token is to be deleted
 	//   type: string
 	//   required: true
 	// - name: token

routers/api/v1/user/block.go

@@ -37,7 +37,7 @@ func CheckUserBlock(ctx *context.APIContext) {
 	// parameters:
 	// - name: username
 	//   in: path
-	//   description: user to check
+	//   description: username of the user to check
 	//   type: string
 	//   required: true
 	// responses:
@@ -56,7 +56,7 @@ func BlockUser(ctx *context.APIContext) {
 	// parameters:
 	// - name: username
 	//   in: path
-	//   description: user to block
+	//   description: username of the user to block
 	//   type: string
 	//   required: true
 	// - name: note
@@ -81,7 +81,7 @@ func UnblockUser(ctx *context.APIContext) {
 	// parameters:
 	// - name: username
 	//   in: path
-	//   description: user to unblock
+	//   description: username of the user to unblock
 	//   type: string
 	//   required: true
 	// responses:

routers/api/v1/user/follower.go

@@ -67,7 +67,7 @@ func ListFollowers(ctx *context.APIContext) {
 	// parameters:
 	// - name: username
 	//   in: path
-	//   description: username of user
+	//   description: username of the user whose followers are to be listed
 	//   type: string
 	//   required: true
 	// - name: page
@@ -131,7 +131,7 @@ func ListFollowing(ctx *context.APIContext) {
 	// parameters:
 	// - name: username
 	//   in: path
-	//   description: username of user
+	//   description: username of the user whose followed users are to be listed
 	//   type: string
 	//   required: true
 	// - name: page
@@ -167,7 +167,7 @@ func CheckMyFollowing(ctx *context.APIContext) {
 	// parameters:
 	// - name: username
 	//   in: path
-	//   description: username of followed user
+	//   description: username of the user to check for authenticated followers
 	//   type: string
 	//   required: true
 	// responses:
@@ -187,12 +187,12 @@ func CheckFollowing(ctx *context.APIContext) {
 	// parameters:
 	// - name: username
 	//   in: path
-	//   description: username of following user
+	//   description: username of the following user
 	//   type: string
 	//   required: true
 	// - name: target
 	//   in: path
-	//   description: username of followed user
+	//   description: username of the followed user
 	//   type: string
 	//   required: true
 	// responses:
@@ -216,7 +216,7 @@ func Follow(ctx *context.APIContext) {
 	// parameters:
 	// - name: username
 	//   in: path
-	//   description: username of user to follow
+	//   description: username of the user to follow
 	//   type: string
 	//   required: true
 	// responses:
@@ -246,7 +246,7 @@ func Unfollow(ctx *context.APIContext) {
 	// parameters:
 	// - name: username
 	//   in: path
-	//   description: username of user to unfollow
+	//   description: username of the user to unfollow
 	//   type: string
 	//   required: true
 	// responses:

routers/api/v1/user/gpg_key.go

@@ -53,7 +53,7 @@ func ListGPGKeys(ctx *context.APIContext) {
 	// parameters:
 	// - name: username
 	//   in: path
-	//   description: username of user
+	//   description: username of the user whose GPG key list is to be obtained
 	//   type: string
 	//   required: true
 	// - name: page

routers/api/v1/user/key.go

@@ -136,7 +136,7 @@ func ListPublicKeys(ctx *context.APIContext) {
 	// parameters:
 	// - name: username
 	//   in: path
-	//   description: username of user
+	//   description: username of the user whose public keys are to be listed
 	//   type: string
 	//   required: true
 	// - name: fingerprint

routers/api/v1/user/repo.go

@@ -62,7 +62,7 @@ func ListUserRepos(ctx *context.APIContext) {
 	// parameters:
 	// - name: username
 	//   in: path
-	//   description: username of user
+	//   description: username of the user whose owned repos are to be listed
 	//   type: string
 	//   required: true
 	// - name: page

routers/api/v1/user/star.go

@@ -50,7 +50,7 @@ func GetStarredRepos(ctx *context.APIContext) {
 	// parameters:
 	// - name: username
 	//   in: path
-	//   description: username of user
+	//   description: username of the user whose starred repos are to be listed
 	//   type: string
 	//   required: true
 	// - name: page

routers/api/v1/user/user.go

@@ -110,7 +110,7 @@ func GetInfo(ctx *context.APIContext) {
 	// parameters:
 	// - name: username
 	//   in: path
-	//   description: username of user to get
+	//   description: username of the user whose data is to be listed
 	//   type: string
 	//   required: true
 	// responses:
@@ -151,7 +151,7 @@ func GetUserHeatmapData(ctx *context.APIContext) {
 	// parameters:
 	// - name: username
 	//   in: path
-	//   description: username of user to get
+	//   description: username of the user whose heatmap is to be obtained
 	//   type: string
 	//   required: true
 	// responses:
@@ -177,7 +177,7 @@ func ListUserActivityFeeds(ctx *context.APIContext) {
 	// parameters:
 	// - name: username
 	//   in: path
-	//   description: username of user
+	//   description: username of the user whose activity feeds are to be listed
 	//   type: string
 	//   required: true
 	// - name: only-performed-by

routers/api/v1/user/watch.go

@@ -49,7 +49,7 @@ func GetWatchedRepos(ctx *context.APIContext) {
 	// - name: username
 	//   type: string
 	//   in: path
-	//   description: username of the user
+	//   description: username of the user whose watched repos are to be listed
 	//   required: true
 	// - name: page
 	//   in: query

templates/swagger/v1_json.tmpl

@@ -766,7 +766,7 @@
           },
           {
             "type": "string",
-            "description": "user's login name to search for",
+            "description": "identifier of the user, provided by the external authenticator",
             "name": "login_name",
             "in": "query"
           },
@@ -842,7 +842,7 @@
         "parameters": [
           {
             "type": "string",
-            "description": "username of user to delete",
+            "description": "username of the user to delete",
             "name": "username",
             "in": "path",
             "required": true
@@ -884,7 +884,7 @@
         "parameters": [
           {
             "type": "string",
-            "description": "username of user to edit",
+            "description": "username of the user whose data is to be edited",
             "name": "username",
             "in": "path",
             "required": true
@@ -926,7 +926,7 @@
         "parameters": [
           {
             "type": "string",
-            "description": "username of user",
+            "description": "username of the user whose badges are to be listed",
             "name": "username",
             "in": "path",
             "required": true
@@ -956,7 +956,7 @@
         "parameters": [
           {
             "type": "string",
-            "description": "username of user",
+            "description": "username of the user to whom a badge is to be added",
             "name": "username",
             "in": "path",
             "required": true
@@ -990,7 +990,7 @@
         "parameters": [
           {
             "type": "string",
-            "description": "username of user",
+            "description": "username of the user whose badge is to be deleted",
             "name": "username",
             "in": "path",
             "required": true
@@ -1032,7 +1032,7 @@
         "parameters": [
           {
             "type": "string",
-            "description": "username of the user",
+            "description": "username of the user who is to receive a public key",
             "name": "username",
             "in": "path",
             "required": true
@@ -1071,7 +1071,7 @@
         "parameters": [
           {
             "type": "string",
-            "description": "username of user",
+            "description": "username of the user whose public key is to be deleted",
             "name": "username",
             "in": "path",
             "required": true
@@ -1114,7 +1114,7 @@
         "parameters": [
           {
             "type": "string",
-            "description": "username of the user that will own the created organization",
+            "description": "username of the user who will own the created organization",
             "name": "username",
             "in": "path",
             "required": true
@@ -1154,7 +1154,7 @@
         "parameters": [
           {
             "type": "string",
-            "description": "existing username of user",
+            "description": "current username of the user",
             "name": "username",
             "in": "path",
             "required": true
@@ -1197,7 +1197,7 @@
         "parameters": [
           {
             "type": "string",
-            "description": "username of the user. This user will own the created repository",
+            "description": "username of the user who will own the created repository",
             "name": "username",
             "in": "path",
             "required": true
@@ -2716,7 +2716,7 @@
           },
           {
             "type": "string",
-            "description": "user to check",
+            "description": "username of the user to check",
             "name": "username",
             "in": "path",
             "required": true
@@ -2747,7 +2747,7 @@
           },
           {
             "type": "string",
-            "description": "user to block",
+            "description": "username of the user to block",
             "name": "username",
             "in": "path",
             "required": true
@@ -2787,7 +2787,7 @@
           },
           {
             "type": "string",
-            "description": "user to unblock",
+            "description": "username of the user to unblock",
             "name": "username",
             "in": "path",
             "required": true
@@ -3258,7 +3258,7 @@
           },
           {
             "type": "string",
-            "description": "username of the user",
+            "description": "username of the user to check for an organization membership",
             "name": "username",
             "in": "path",
             "required": true
@@ -3295,7 +3295,7 @@
           },
           {
             "type": "string",
-            "description": "username of the user",
+            "description": "username of the user to remove from the organization",
             "name": "username",
             "in": "path",
             "required": true
@@ -3369,7 +3369,7 @@
           },
           {
             "type": "string",
-            "description": "username of the user",
+            "description": "username of the user to check for a public organization membership",
             "name": "username",
             "in": "path",
             "required": true
@@ -3403,7 +3403,7 @@
           },
           {
             "type": "string",
-            "description": "username of the user",
+            "description": "username of the user whose membership is to be publicized",
             "name": "username",
             "in": "path",
             "required": true
@@ -3440,7 +3440,7 @@
           },
           {
             "type": "string",
-            "description": "username of the user",
+            "description": "username of the user whose membership is to be concealed",
             "name": "username",
             "in": "path",
             "required": true
@@ -6930,7 +6930,7 @@
           },
           {
             "type": "string",
-            "description": "username of the collaborator",
+            "description": "username of the user to check for being a collaborator",
             "name": "collaborator",
             "in": "path",
             "required": true
@@ -6974,7 +6974,7 @@
           },
           {
             "type": "string",
-            "description": "username of the collaborator to add",
+            "description": "username of the user to add or update as a collaborator",
             "name": "collaborator",
             "in": "path",
             "required": true
@@ -7074,7 +7074,7 @@
           },
           {
             "type": "string",
-            "description": "username of the collaborator",
+            "description": "username of the collaborator whose permissions are to be obtained",
             "name": "collaborator",
             "in": "path",
             "required": true
@@ -11951,7 +11951,7 @@
           },
           {
             "type": "string",
-            "description": "user to subscribe",
+            "description": "username of the user to subscribe the issue to",
             "name": "user",
             "in": "path",
             "required": true
@@ -12009,7 +12009,7 @@
           },
           {
             "type": "string",
-            "description": "user witch unsubscribe",
+            "description": "username of the user to unsubscribe from an issue",
             "name": "user",
             "in": "path",
             "required": true
@@ -16821,7 +16821,7 @@
           },
           {
             "type": "string",
-            "description": "username of user",
+            "description": "username of the user whose tracked times are to be listed",
             "name": "user",
             "in": "path",
             "required": true
@@ -17844,7 +17844,7 @@
           },
           {
             "type": "string",
-            "description": "username of the member to list",
+            "description": "username of the user whose data is to be listed",
             "name": "username",
             "in": "path",
             "required": true
@@ -17879,7 +17879,7 @@
           },
           {
             "type": "string",
-            "description": "username of the user to add",
+            "description": "username of the user to add to a team",
             "name": "username",
             "in": "path",
             "required": true
@@ -17917,7 +17917,7 @@
           },
           {
             "type": "string",
-            "description": "username of the user to remove",
+            "description": "username of the user to remove from a team",
             "name": "username",
             "in": "path",
             "required": true
@@ -18896,7 +18896,7 @@
         "parameters": [
           {
             "type": "string",
-            "description": "user to check",
+            "description": "username of the user to check",
             "name": "username",
             "in": "path",
             "required": true
@@ -18920,7 +18920,7 @@
         "parameters": [
           {
             "type": "string",
-            "description": "user to block",
+            "description": "username of the user to block",
             "name": "username",
             "in": "path",
             "required": true
@@ -18953,7 +18953,7 @@
         "parameters": [
           {
             "type": "string",
-            "description": "user to unblock",
+            "description": "username of the user to unblock",
             "name": "username",
             "in": "path",
             "required": true
@@ -19115,7 +19115,7 @@
         "parameters": [
           {
             "type": "string",
-            "description": "username of followed user",
+            "description": "username of the user to check for authenticated followers",
             "name": "username",
             "in": "path",
             "required": true
@@ -19139,7 +19139,7 @@
         "parameters": [
           {
             "type": "string",
-            "description": "username of user to follow",
+            "description": "username of the user to follow",
             "name": "username",
             "in": "path",
             "required": true
@@ -19166,7 +19166,7 @@
         "parameters": [
           {
             "type": "string",
-            "description": "username of user to unfollow",
+            "description": "username of the user to unfollow",
             "name": "username",
             "in": "path",
             "required": true
@@ -20120,7 +20120,7 @@
         "parameters": [
           {
             "type": "string",
-            "description": "username of user to get",
+            "description": "username of the user whose data is to be listed",
             "name": "username",
             "in": "path",
             "required": true
@@ -20149,7 +20149,7 @@
         "parameters": [
           {
             "type": "string",
-            "description": "username of user",
+            "description": "username of the user whose activity feeds are to be listed",
             "name": "username",
             "in": "path",
             "required": true
@@ -20203,7 +20203,7 @@
         "parameters": [
           {
             "type": "string",
-            "description": "username of user",
+            "description": "username of the user whose followers are to be listed",
             "name": "username",
             "in": "path",
             "required": true
@@ -20244,7 +20244,7 @@
         "parameters": [
           {
             "type": "string",
-            "description": "username of user",
+            "description": "username of the user whose followed users are to be listed",
             "name": "username",
             "in": "path",
             "required": true
@@ -20282,14 +20282,14 @@
         "parameters": [
           {
             "type": "string",
-            "description": "username of following user",
+            "description": "username of the following user",
             "name": "username",
             "in": "path",
             "required": true
           },
           {
             "type": "string",
-            "description": "username of followed user",
+            "description": "username of the followed user",
             "name": "target",
             "in": "path",
             "required": true
@@ -20318,7 +20318,7 @@
         "parameters": [
           {
             "type": "string",
-            "description": "username of user",
+            "description": "username of the user whose GPG key list is to be obtained",
             "name": "username",
             "in": "path",
             "required": true
@@ -20359,7 +20359,7 @@
         "parameters": [
           {
             "type": "string",
-            "description": "username of user to get",
+            "description": "username of the user whose heatmap is to be obtained",
             "name": "username",
             "in": "path",
             "required": true
@@ -20388,7 +20388,7 @@
         "parameters": [
           {
             "type": "string",
-            "description": "username of user",
+            "description": "username of the user whose public keys are to be listed",
             "name": "username",
             "in": "path",
             "required": true
@@ -20435,7 +20435,7 @@
         "parameters": [
           {
             "type": "string",
-            "description": "username of user",
+            "description": "username of the user whose organizations are to be listed",
             "name": "username",
             "in": "path",
             "required": true
@@ -20476,7 +20476,7 @@
         "parameters": [
           {
             "type": "string",
-            "description": "username of user",
+            "description": "username of the user whose permissions are to be obtained",
             "name": "username",
             "in": "path",
             "required": true
@@ -20515,7 +20515,7 @@
         "parameters": [
           {
             "type": "string",
-            "description": "username of user",
+            "description": "username of the user whose owned repos are to be listed",
             "name": "username",
             "in": "path",
             "required": true
@@ -20556,7 +20556,7 @@
         "parameters": [
           {
             "type": "string",
-            "description": "username of user",
+            "description": "username of the user whose starred repos are to be listed",
             "name": "username",
             "in": "path",
             "required": true
@@ -20600,7 +20600,7 @@
         "parameters": [
           {
             "type": "string",
-            "description": "username of the user",
+            "description": "username of the user whose watched repos are to be listed",
             "name": "username",
             "in": "path",
             "required": true
@@ -20641,7 +20641,7 @@
         "parameters": [
           {
             "type": "string",
-            "description": "username of user",
+            "description": "username of to user whose access tokens are to be listed",
             "name": "username",
             "in": "path",
             "required": true
@@ -20683,7 +20683,7 @@
         "parameters": [
           {
             "type": "string",
-            "description": "username of user",
+            "description": "username of the user whose token is to be created",
             "name": "username",
             "in": "path",
             "required": true
@@ -20722,7 +20722,7 @@
         "parameters": [
           {
             "type": "string",
-            "description": "username of user",
+            "description": "username of the user whose token is to be deleted",
             "name": "username",
             "in": "path",
             "required": true
@@ -21523,7 +21523,7 @@
           "x-go-name": "Time"
         },
         "user_name": {
-          "description": "User who spent the time (optional)",
+          "description": "username of the user who spent the time working on the issue (optional)",
           "type": "string",
           "x-go-name": "User"
         }
@@ -23058,6 +23058,7 @@
           "x-go-name": "RepoAdminChangeTeamAccess"
         },
         "username": {
+          "description": "username of the organization",
           "type": "string",
           "x-go-name": "UserName"
         },
@@ -23508,7 +23509,9 @@
           "x-go-name": "FullName"
         },
         "login_name": {
+          "description": "identifier of the user, provided by the external authenticator (if configured)",
           "type": "string",
+          "default": "empty",
           "x-go-name": "LoginName"
         },
         "must_change_password": {
@@ -23533,6 +23536,7 @@
           "x-go-name": "SourceID"
         },
         "username": {
+          "description": "username of the user",
           "type": "string",
           "x-go-name": "Username"
         },
@@ -24518,7 +24522,9 @@
           "x-go-name": "Location"
         },
         "login_name": {
+          "description": "identifier of the user, provided by the external authenticator (if configured)",
           "type": "string",
+          "default": "empty",
           "x-go-name": "LoginName"
         },
         "max_repo_creation": {
@@ -24577,6 +24583,7 @@
           "x-go-name": "UserID"
         },
         "username": {
+          "description": "username of the user",
           "type": "string",
           "x-go-name": "UserName"
         },
@@ -26301,7 +26308,7 @@
           "x-go-name": "RepoAdminChangeTeamAccess"
         },
         "username": {
-          "description": "deprecated",
+          "description": "username of the organization\ndeprecated",
           "type": "string",
           "x-go-name": "UserName"
         },
@@ -26545,6 +26552,7 @@
           "x-go-name": "Name"
         },
         "username": {
+          "description": "username of the user",
           "type": "string",
           "x-go-name": "UserName"
         }
@@ -28008,6 +28016,7 @@
           "x-go-name": "UserID"
         },
         "user_name": {
+          "description": "username of the user",
           "type": "string",
           "x-go-name": "UserName"
         }
@@ -28249,12 +28258,12 @@
           "x-go-name": "Location"
         },
         "login": {
-          "description": "the user's username",
+          "description": "login of the user, same as `username`",
           "type": "string",
           "x-go-name": "UserName"
         },
         "login_name": {
-          "description": "the user's authentication sign-in name.",
+          "description": "identifier of the user, provided by the external authenticator (if configured)",
           "type": "string",
           "default": "empty",
           "x-go-name": "LoginName"