Repository navigation
Description
How to use GitHub
- Please use the 👍 reaction to show that you are interested into the same feature.
- Please don't comment if you have no relevant information to add. It's just extra noise for everyone subscribed to this issue.
- Subscribe to receive notifications on status change and new comments.
Feature request
Which Nextcloud Version are you currently using: not version specific, this is about the generated specs.
Is your feature request related to a problem? Please describe.
#401 documents uploaded files by detecting $this->request->getUploadedFile('name') in the route method. As @lfals pointed out in #401 (comment), some endpoints in Nextcloud apps can not be described from the code alone:
- Required files. Collectives
PageController::uploadAttachment()rejects a missing file, butgetUploadedFile()returnsnullfor a missing field, so the file is documented as optional. - Several files. Forms
ApiController::uploadFiles()and TalkTempAvatarController::postAvatar()read the upload in PHP's array form (files[], such as$files['error'][0]). The schema describes a singlefilespart, and a request with onefilespart is rejected by both. - Field name and key. The multipart field (
files[]) is not the same as thegetUploadedFile()key (files). - Indirect reads. Mail
MessageApiController::handleAttachments()reads the upload in a private helper, so the route method shows no upload. - Different request formats. An endpoint that accepts JSON and multipart with different structures gets the JSON schema copied into the multipart body.
Describe the solution you'd like
Keep automatic detection as the default and add optional declarative metadata for the cases above. The extractor would read it the same way it reads RequestHeader, which already has indirect: true for headers read outside the controller method. For example (illustrative, not part of OCP):
#[RequestFile(
requestKey: 'files',
fieldName: 'files[]',
multiple: true,
required: true,
indirect: true,
)]
public function uploadFiles(): DataResponse {
return $this->handleUpload();
}The attribute itself would have to be added to OCP in nextcloud/server first. For endpoints whose JSON and multipart bodies differ, explicit request body metadata may be needed instead.
Regression tests should cover required and optional files, multiple uploads, indirect access and alternative request formats. Both requestBody.required and the required list of the schema should match the endpoint.
Describe alternatives you've considered
Warnings when the code suggests one of these cases. A read in a private method of the same controller could be found, but ControllerMethod::parse() only gets the route method today, and getParam() has the same gap. For files[], Talk indexes $files['error'][0] and Forms uses a nested foreach. A check could catch those two shapes, but it would miss a read that is passed to a service, so the lack of a warning would not mean the schema is right.
Activity
lfals commentedon Nov 18, 2026
Working on this!
feat: Add RequestFile attribute to describe uploaded files
lfals commentedon Nov 18, 2026
I'm waiting for #401 to be merged before finishing this PR. #404 builds on its multipart request body detection, so the branch currently contains the #401 commit. Once it is merged I'll rebase onto
main, so the PR only shows theRequestFilechanges, and open it for review.The extractor side is already done and tested against a Nextcloud instance in Docker. The
RequestFileattribute still has to be added to OCP in nextcloud/server.feat: Add RequestFile attribute to describe uploaded files