Fixes #7023 - API Org Visibility (#7028)

3 files changed, 49 insertions, 20 deletions

diff --git a/modules/structs/org.go b/modules/structs/org.go
index fd15da1ce9..08ab139975 100644
--- a/modules/structs/org.go
+++ b/modules/structs/org.go
@@ -6,25 +6,27 @@ package structs
 
 // Organization represents an organization
 type Organization struct {
-	ID          int64       `json:"id"`
-	UserName    string      `json:"username"`
-	FullName    string      `json:"full_name"`
-	AvatarURL   string      `json:"avatar_url"`
-	Description string      `json:"description"`
-	Website     string      `json:"website"`
-	Location    string      `json:"location"`
-	Visibility  VisibleType `json:"visibility"`
+	ID          int64  `json:"id"`
+	UserName    string `json:"username"`
+	FullName    string `json:"full_name"`
+	AvatarURL   string `json:"avatar_url"`
+	Description string `json:"description"`
+	Website     string `json:"website"`
+	Location    string `json:"location"`
+	Visibility  string `json:"visibility"`
 }
 
 // CreateOrgOption options for creating an organization
 type CreateOrgOption struct {
 	// required: true
-	UserName    string      `json:"username" binding:"Required"`
-	FullName    string      `json:"full_name"`
-	Description string      `json:"description"`
-	Website     string      `json:"website"`
-	Location    string      `json:"location"`
-	Visibility  VisibleType `json:"visibility"`
+	UserName    string `json:"username" binding:"Required"`
+	FullName    string `json:"full_name"`
+	Description string `json:"description"`
+	Website     string `json:"website"`
+	Location    string `json:"location"`
+	// possible values are `public` (default), `limited` or `private`
+	// enum: public,limited,private
+	Visibility string `json:"visibility" binding:"In(,public,limited,private)"`
 }
 
 // EditOrgOption options for editing an organization
@@ -33,4 +35,7 @@ type EditOrgOption struct {
 	Description string `json:"description"`
 	Website     string `json:"website"`
 	Location    string `json:"location"`
+	// possible values are `public`, `limited` or `private`
+	// enum: public,limited,private
+	Visibility string `json:"visibility" binding:"In(,public,limited,private)"`
 }
diff --git a/modules/structs/org_type.go b/modules/structs/org_type.go
index 86dc5c81cd..4fb9b6fc0f 100644
--- a/modules/structs/org_type.go
+++ b/modules/structs/org_type.go
@@ -40,6 +40,16 @@ func (vt VisibleType) IsPrivate() bool {
 	return vt == VisibleTypePrivate
 }
 
+// VisibilityString provides the mode string of the visibility type (public, limited, private)
+func (vt VisibleType) String() string {
+	for k, v := range VisibilityModes {
+		if vt == v {
+			return k
+		}
+	}
+	return ""
+}
+
 // ExtractKeysFromMapString provides a slice of keys from map
 func ExtractKeysFromMapString(in map[string]VisibleType) (keys []string) {
 	for k := range in {
diff --git a/modules/structs/repo_file.go b/modules/structs/repo_file.go
index ac8b9333fe..c447d26724 100644
--- a/modules/structs/repo_file.go
+++ b/modules/structs/repo_file.go
@@ -7,29 +7,43 @@ package structs
 
 // FileOptions options for all file APIs
 type FileOptions struct {
-	Message       string   `json:"message" binding:"Required"`
-	BranchName    string   `json:"branch"`
-	NewBranchName string   `json:"new_branch"`
-	Author        Identity `json:"author"`
-	Committer     Identity `json:"committer"`
+	// message (optional) for the commit of this file. if not supplied, a default message will be used
+	Message string `json:"message" binding:"Required"`
+	// branch (optional) to base this file from. if not given, the default branch is used
+	BranchName string `json:"branch"`
+	// new_branch (optional) will make a new branch from `branch` before creating the file
+	NewBranchName string `json:"new_branch"`
+	// `author` and `committer` are optional (if only one is given, it will be used for the other, otherwise the authenticated user will be used)
+	Author    Identity `json:"author"`
+	Committer Identity `json:"committer"`
 }
 
 // CreateFileOptions options for creating files
+// Note: `author` and `committer` are optional (if only one is given, it will be used for the other, otherwise the authenticated user will be used)
 type CreateFileOptions struct {
 	FileOptions
+	// content must be base64 encoded
+	// required: true
 	Content string `json:"content"`
 }
 
 // DeleteFileOptions options for deleting files (used for other File structs below)
+// Note: `author` and `committer` are optional (if only one is given, it will be used for the other, otherwise the authenticated user will be used)
 type DeleteFileOptions struct {
 	FileOptions
+	// sha is the SHA for the file that already exists
+	// required: true
 	SHA string `json:"sha" binding:"Required"`
 }
 
 // UpdateFileOptions options for updating files
+// Note: `author` and `committer` are optional (if only one is given, it will be used for the other, otherwise the authenticated user will be used)
 type UpdateFileOptions struct {
 	DeleteFileOptions
-	Content  string `json:"content"`
+	// content must be base64 encoded
+	// required: true
+	Content string `json:"content"`
+	// from_path (optional) is the path of the original file which will be moved/renamed to the path in the URL
 	FromPath string `json:"from_path" binding:"MaxSize(500)"`
 }