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

Issue: [link](go-gitea#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

Author: AlexMaryW

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