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)
This commit is contained in:
Denys Konovalov 2023-06-07 17:49:58 +02:00 committed by GitHub
parent 027014d7de
commit eac1bddb8d
No known key found for this signature in database
GPG key ID: 4AEE18F83AFDEB23
3 changed files with 16 additions and 10 deletions

View file

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

View file

@ -408,11 +408,11 @@ func canReadFiles(r *context.Repository) bool {
return r.Permission.CanRead(unit.TypeCode) 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) { func ChangeFiles(ctx *context.APIContext) {
// swagger:operation POST /repos/{owner}/{repo}/contents repository repoChangeFiles // 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: // consumes:
// - application/json // - application/json
// produces: // produces:

View file

@ -4074,7 +4074,7 @@
"tags": [ "tags": [
"repository" "repository"
], ],
"summary": "Create or update multiple files in a repository", "summary": "Modify multiple files in a repository",
"operationId": "repoChangeFiles", "operationId": "repoChangeFiles",
"parameters": [ "parameters": [
{ {
@ -15947,11 +15947,11 @@
"type": "object", "type": "object",
"required": [ "required": [
"operation", "operation",
"content" "path"
], ],
"properties": { "properties": {
"content": { "content": {
"description": "content must be base64 encoded", "description": "new or updated file content, must be base64 encoded",
"type": "string", "type": "string",
"x-go-name": "Content" "x-go-name": "Content"
}, },
@ -15976,7 +15976,7 @@
"x-go-name": "Path" "x-go-name": "Path"
}, },
"sha": { "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", "type": "string",
"x-go-name": "SHA" "x-go-name": "SHA"
} }
@ -15986,6 +15986,9 @@
"ChangeFilesOptions": { "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)", "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", "type": "object",
"required": [
"files"
],
"properties": { "properties": {
"author": { "author": {
"$ref": "#/definitions/Identity" "$ref": "#/definitions/Identity"
@ -16002,6 +16005,7 @@
"$ref": "#/definitions/CommitDateOptions" "$ref": "#/definitions/CommitDateOptions"
}, },
"files": { "files": {
"description": "list of file operations",
"type": "array", "type": "array",
"items": { "items": {
"$ref": "#/definitions/ChangeFileOperation" "$ref": "#/definitions/ChangeFileOperation"