From eac1bddb8da2e26a3f6d6678b9888c65418cf318 Mon Sep 17 00:00:00 2001
From: Denys Konovalov <kontakt@denyskon.de>
Date: Wed, 7 Jun 2023 17:49:58 +0200
Subject: [PATCH] fix swagger documentation for multiple files API endpoint
 (#25110)

Fixes some issues with the swagger documentation for the new multiple
files API endpoint (#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   | 10 ++++++----
 routers/api/v1/repo/file.go    |  4 ++--
 templates/swagger/v1_json.tmpl | 12 ++++++++----
 3 files changed, 16 insertions(+), 10 deletions(-)

diff --git a/modules/structs/repo_file.go b/modules/structs/repo_file.go
index 6ca0e1c101..48fcebe6f8 100644
--- a/modules/structs/repo_file.go
+++ b/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
diff --git a/routers/api/v1/repo/file.go b/routers/api/v1/repo/file.go
index ae0d31c2a6..e25def6df2 100644
--- a/routers/api/v1/repo/file.go
+++ b/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:
diff --git a/templates/swagger/v1_json.tmpl b/templates/swagger/v1_json.tmpl
index 75492ab631..e78c077fc3 100644
--- a/templates/swagger/v1_json.tmpl
+++ b/templates/swagger/v1_json.tmpl
@@ -4074,7 +4074,7 @@
         "tags": [
           "repository"
         ],
-        "summary": "Create or update multiple files in a repository",
+        "summary": "Modify multiple files in a repository",
         "operationId": "repoChangeFiles",
         "parameters": [
           {
@@ -15947,11 +15947,11 @@
       "type": "object",
       "required": [
         "operation",
-        "content"
+        "path"
       ],
       "properties": {
         "content": {
-          "description": "content must be base64 encoded",
+          "description": "new or updated file content, must be base64 encoded",
           "type": "string",
           "x-go-name": "Content"
         },
@@ -15976,7 +15976,7 @@
           "x-go-name": "Path"
         },
         "sha": {
-          "description": "sha is the SHA for the file that already exists, required for update, delete",
+          "description": "sha is the SHA for the file that already exists, required for update or delete",
           "type": "string",
           "x-go-name": "SHA"
         }
@@ -15986,6 +15986,9 @@
     "ChangeFilesOptions": {
       "description": "ChangeFilesOptions options for creating, updating or deleting multiple files\nNote: `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": "object",
+      "required": [
+        "files"
+      ],
       "properties": {
         "author": {
           "$ref": "#/definitions/Identity"
@@ -16002,6 +16005,7 @@
           "$ref": "#/definitions/CommitDateOptions"
         },
         "files": {
+          "description": "list of file operations",
           "type": "array",
           "items": {
             "$ref": "#/definitions/ChangeFileOperation"