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"