fix swagger documentation for multiple files API endpoint (go-gitea#2…

…5110)

Fixes some issues with the swagger documentation for the new multiple
files API endpoint (go-gitea#24887) which were overlooked when submitting the
original PR:

1. add some missing parameter descriptions
2. set correct `required` option for required parameters
3. change endpoint description to match it full functionality (every
kind of file modification is supported, not just creating and updating)

modules/structs/repo_file.go

@@ -71,11 +71,11 @@ type ChangeFileOperation struct {
 	// enum: create,update,delete
 	Operation string `json:"operation" binding:"Required"`
 	// path to the existing or new file
-	Path string `json:"path" binding:"MaxSize(500)"`
-	// content must be base64 encoded
 	// required: true
+	Path string `json:"path" binding:"Required;MaxSize(500)"`
+	// new or updated file content, must be base64 encoded
 	Content string `json:"content"`
-	// sha is the SHA for the file that already exists, required for update, delete
+	// sha is the SHA for the file that already exists, required for update or delete
 	SHA string `json:"sha"`
 	// old path of the file to move
 	FromPath string `json:"from_path"`
@@ -85,7 +85,9 @@ type ChangeFileOperation struct {
 // 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 ChangeFilesOptions struct {
 	FileOptions
-	Files []*ChangeFileOperation `json:"files"`
+	// list of file operations
+	// required: true
+	Files []*ChangeFileOperation `json:"files" binding:"Required"`
 }
 
 // Branch returns branch name

routers/api/v1/repo/file.go

@@ -408,11 +408,11 @@ func canReadFiles(r *context.Repository) bool {
 	return r.Permission.CanRead(unit.TypeCode)
 }
 
-// ChangeFiles handles API call for creating or updating multiple files
+// ChangeFiles handles API call for modifying multiple files
 func ChangeFiles(ctx *context.APIContext) {
 	// swagger:operation POST /repos/{owner}/{repo}/contents repository repoChangeFiles
 	// ---
-	// summary: Create or update multiple files in a repository
+	// summary: Modify multiple files in a repository
 	// consumes:
 	// - application/json
 	// produces: