7 files changed, 27 insertions, 14 deletions
diff --git a/modules/structs/admin_user.go b/modules/structs/admin_user.go
index f7c6d10ba0..c68b59a897 100644
--- a/modules/structs/admin_user.go
+++ b/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
diff --git a/modules/structs/hook.go b/modules/structs/hook.go
index 6e0b66ef55..ac779a5740 100644
--- a/modules/structs/hook.go
+++ b/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"`
 }
 
diff --git a/modules/structs/issue_tracked_time.go b/modules/structs/issue_tracked_time.go
index a3904af80e..befcfb323d 100644
--- a/modules/structs/issue_tracked_time.go
+++ b/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"`
diff --git a/modules/structs/org.go b/modules/structs/org.go
index f93b3b6493..33b45c6344 100644
--- a/modules/structs/org.go
+++ b/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)"`
diff --git a/modules/structs/repo_file.go b/modules/structs/repo_file.go
index 91ee060d50..5a86db868b 100644
--- a/modules/structs/repo_file.go
+++ b/modules/structs/repo_file.go
@@ -116,14 +116,17 @@ type ContentsExtResponse struct {
 
 // ContentsResponse contains information about a repo's entry's (dir, file, symlink, submodule) metadata and content
 type ContentsResponse struct {
-	Name          string `json:"name"`
-	Path          string `json:"path"`
-	SHA           string `json:"sha"`
-	LastCommitSHA string `json:"last_commit_sha"`
+	Name string `json:"name"`
+	Path string `json:"path"`
+	SHA  string `json:"sha"`
+
+	LastCommitSHA *string `json:"last_commit_sha,omitempty"`
 	// swagger:strfmt date-time
-	LastCommitterDate time.Time `json:"last_committer_date"`
+	LastCommitterDate *time.Time `json:"last_committer_date,omitempty"`
 	// swagger:strfmt date-time
-	LastAuthorDate time.Time `json:"last_author_date"`
+	LastAuthorDate    *time.Time `json:"last_author_date,omitempty"`
+	LastCommitMessage *string    `json:"last_commit_message,omitempty"`
+
 	// `type` will be `file`, `dir`, `symlink`, or `submodule`
 	Type string `json:"type"`
 	Size int64  `json:"size"`
@@ -141,8 +144,8 @@ type ContentsResponse struct {
 	SubmoduleGitURL *string            `json:"submodule_git_url"`
 	Links           *FileLinksResponse `json:"_links"`
 
-	LfsOid  *string `json:"lfs_oid"`
-	LfsSize *int64  `json:"lfs_size"`
+	LfsOid  *string `json:"lfs_oid,omitempty"`
+	LfsSize *int64  `json:"lfs_size,omitempty"`
 }
 
 // FileCommitResponse contains information generated from a Git commit for a repo's file.
diff --git a/modules/structs/user.go b/modules/structs/user.go
index 7338e45739..89349cda2c 100644
--- a/modules/structs/user.go
+++ b/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
diff --git a/modules/structs/user_email.go b/modules/structs/user_email.go
index 9319667e8f..01895a0058 100644
--- a/modules/structs/user_email.go
+++ b/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"`
 }