Repository navigation
feat: Document uploaded files as multipart request bodies - #401
mateuscmtropical wants to merge 1 commit into
Conversation
Signed-off-by: mateuscmtropical <mateuscmtropical@gmail.com>
|
Thanks a lot for looking into this! I hope I'll find some time to try it out in the coming days. Looked good at a first glance. |
|
Thanks for working on #343. Automatically detecting Looking at existing applications maintained by the Nextcloud organization, there are cases where automatic detection alone cannot accurately describe the multipart contract:
Could we complement automatic detection with optional declarative metadata for cases that cannot be inferred reliably? Nextcloud already provides a precedent through A similar attribute could look like this: // Illustrative API, not currently part of OCP.
#[RequestFile(
requestKey: 'files',
fieldName: 'files[]',
multiple: true,
required: true,
indirect: true,
)]
public function uploadFiles(): DataResponse {
return $this->handleUpload();
}This would distinguish the For endpoints supporting both JSON and multipart with different request structures, explicit request-body metadata might also be necessary instead of automatically copying the JSON schema. I would suggest adding regression tests for required and optional files, multiple uploads, indirect access, and alternative request formats. Both I'm not suggesting that a new OCP attribute should block #401. Automatic detection can remain the default, with explicit metadata introduced separately when inference is insufficient. If this is outside the current PR's scope, could we agree on the declarative approach as a follow-up and ensure unsupported cases do not silently produce misleading schemas? What do you think? |
|
Thanks for checking these apps, that is very useful. I agree. Automatic detection stays the default, and an attribute like The cases this PR can't infer are listed under "Known limitations" in the description: an upload read in a helper gets no multipart body, a |
Fixes #343
Controller methods that call
$this->request->getUploadedFile('name')now get amultipart/form-datarequest body. Each uploaded file is astringproperty withformat: binary. Detection works the same way as forgetParam()andgetHeader().requiredlist. The existingapplication/jsonbody stays, so clients that do not upload a file can still send JSON.getUploadedFile()returnsnullwhen the field is missing.$_FILESfor POST. Other verbs log a warning.getUploadedFile($key), logs a warning and is skipped, so existing apps do not start failing.Known limitations:
getParam().files[]) is documented as a single binary, since the code does not show how many files are expected.Tests: added two fixture endpoints (body parameter plus files, and file only) and regenerated the test specs. I also ran the patched tool on LibreSign. Five upload endpoints got a multipart body (
account/pfx,file/validate,file/{uuid}/add-file,admin/signature-background,admin/certificate-policy) and nothing else changed.