Skip to content

Describe uploaded files that can not be detected from the code #404

Open

Description

@mateuscmtropical

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, but getUploadedFile() returns null for a missing field, so the file is documented as optional.
  • Several files. Forms ApiController::uploadFiles() and Talk TempAvatarController::postAvatar() read the upload in PHP's array form (files[], such as $files['error'][0]). The schema describes a single files part, and a request with one files part is rejected by both.
  • Field name and key. The multipart field (files[]) is not the same as the getUploadedFile() 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.

Additional context
Follow-up of #401 and #343.

Activity

  1. lfals commented on Nov 18, 2026

    @lfals

    Working on this!

  2. added a commit that references this issue on Nov 18, 2026
    1a60688
  3. lfals commented on Nov 18, 2026

    @lfals

    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 the RequestFile changes, and open it for review.

    The extractor side is already done and tested against a Nextcloud instance in Docker. The RequestFile attribute still has to be added to OCP in nextcloud/server.

  4. added a commit that references this issue on Nov 19, 2026
    88666d7
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

No one assigned

    Labels

    No labels
    No labels

    Type

    No type

    Projects

    No projects

      Milestone

      No milestone

      Relationships

      None yet

      Development

      No branches or pull requests

      Issue actions