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 |
|
Thanks, that sounds good to me as a follow-up. Yes, please open the issue. Two small suggestions for this PR in the meantime:
I'm also still curious whether a warning is feasible for the helper-method and |
|
Thanks. I opened #404 for the follow-up and updated the description:
About warnings, I looked at both cases and left them out of this PR:
I added both to #404 as alternatives, since the attribute would describe these cases directly. |
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.$_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 singlefilespart. Endpoints such as Talk'sTempAvatarController::postAvatar()and Forms'ApiController::uploadFiles()read the upload in PHP's array form ($files['error'][0]). A request with onefilespart fills scalar fields instead, so Talk returns "Invalid file provided" and Forms throws "No files provided". I reproduced their access patterns with a small script, not the apps themselves. Generated clients should not be used for these endpoints until the schema can describe them.getUploadedFile()returnsnullwhen the field is missing. They are not in the schema'srequiredlist, and a route with only uploaded files getsrequestBody.required: false.The follow-up for these three cases is #404.
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.