From f36852eead3bf2da8b2bd63782d5eb02901b38fb Mon Sep 17 00:00:00 2001 From: mateuscmtropical Date: Tue, 10 Nov 2026 20:58:06 -0300 Subject: [PATCH 1/3] feat: Document uploaded files as multipart request bodies Signed-off-by: mateuscmtropical --- generate-spec.php | 34 ++- src/ControllerMethod.php | 16 +- tests/appinfo/routes.php | 2 + tests/lib/Controller/SettingsController.php | 29 ++ tests/openapi-administration.json | 313 ++++++++++++++++++++ tests/openapi-full.json | 313 ++++++++++++++++++++ 6 files changed, 700 insertions(+), 7 deletions(-) diff --git a/generate-spec.php b/generate-spec.php index 77d068c..108d2ad 100755 --- a/generate-spec.php +++ b/generate-spec.php @@ -824,7 +824,14 @@ } $operation['security'] = $security; - if ($bodyParameters !== []) { + $uploadedFiles = []; + if (strtolower($route->verb) === 'post') { + $uploadedFiles = $route->controllerMethod->uploadedFiles; + } elseif ($route->controllerMethod->uploadedFiles !== []) { + Logger::warning($route->name, 'Uploaded files are only available in POST requests'); + } + + if ($bodyParameters !== [] || $uploadedFiles !== []) { $requiredBodyParameters = []; foreach ($bodyParameters as $bodyParameter) { @@ -847,13 +854,28 @@ $schema['properties'][$bodyParameter->name] = $bodyParameter->type->toArray($schemas); } + $content = []; + if ($bodyParameters !== []) { + $content['application/json'] = [ + 'schema' => $schema, + ]; + } + if ($uploadedFiles !== []) { + $multipartSchema = $schema; + foreach ($uploadedFiles as $uploadedFile) { + $multipartSchema['properties'][$uploadedFile] = [ + 'type' => 'string', + 'format' => 'binary', + ]; + } + $content['multipart/form-data'] = [ + 'schema' => $multipartSchema, + ]; + } + $operation['requestBody'] = [ 'required' => $required, - 'content' => [ - 'application/json' => [ - 'schema' => $schema, - ], - ], + 'content' => $content, ]; } diff --git a/src/ControllerMethod.php b/src/ControllerMethod.php index e92a45c..2d75d17 100644 --- a/src/ControllerMethod.php +++ b/src/ControllerMethod.php @@ -7,10 +7,12 @@ namespace OpenAPIExtractor; +use PhpParser\Node\Arg; use PhpParser\Node\AttributeGroup; use PhpParser\Node\Expr\MethodCall; use PhpParser\Node\Expr\PropertyFetch; use PhpParser\Node\Expr\Variable; +use PhpParser\Node\Scalar\String_; use PhpParser\Node\Stmt\ClassMethod; use PhpParser\Node\Stmt\Return_; use PHPStan\PhpDocParser\Ast\PhpDoc\DeprecatedTagValueNode; @@ -289,6 +291,7 @@ class ControllerMethod { * @param OpenApiType[] $returns * @param array $responseDescription * @param string[] $description + * @param list $uploadedFiles */ public function __construct( public array $parameters, @@ -298,6 +301,7 @@ public function __construct( public array $description, public ?string $summary, public bool $isDeprecated, + public array $uploadedFiles, ) { } @@ -610,6 +614,7 @@ public static function parse(string $context, } $codeRequestHeaders = []; + $uploadedFiles = []; foreach ($nodeFinder->findInstanceOf($method->getStmts(), MethodCall::class) as $methodCall) { if ($methodCall->var instanceof PropertyFetch && $methodCall->var->var instanceof Variable @@ -654,6 +659,15 @@ public static function parse(string $context, $parameters[] = new ControllerMethodParameter($context, $definitions, $name, $type); } + if ($methodCall->name->name === 'getUploadedFile') { + $arg = $methodCall->args[0] ?? null; + if (!$arg instanceof Arg || !$arg->value instanceof String_) { + Logger::warning($context, 'getUploadedFile() is not called with a string literal, so the uploaded file can not be documented.'); + continue; + } + + $uploadedFiles[] = $arg->value->value; + } } } @@ -713,7 +727,7 @@ public static function parse(string $context, Logger::error($context, 'Unused request header descriptions: ' . implode(', ', $unusedRequestHeaders)); } - return new ControllerMethod($parameters, $attributeRequestHeaders, $responses, $responseDescriptions, $methodDescription, $methodSummary, $isDeprecated); + return new ControllerMethod($parameters, $attributeRequestHeaders, $responses, $responseDescriptions, $methodDescription, $methodSummary, $isDeprecated, array_values(array_unique($uploadedFiles))); } private static function cleanHeaderName(string $header): string { diff --git a/tests/appinfo/routes.php b/tests/appinfo/routes.php index 0ef05cd..4a01c00 100644 --- a/tests/appinfo/routes.php +++ b/tests/appinfo/routes.php @@ -88,6 +88,8 @@ ['name' => 'Settings#samePathPost', 'url' => '/api/{apiVersion}/same-path', 'verb' => 'POST', 'requirements' => ['apiVersion' => '(v2)']], ['name' => 'Settings#requestHeader', 'url' => '/api/{apiVersion}/request-header', 'verb' => 'POST', 'requirements' => ['apiVersion' => '(v2)']], ['name' => 'Settings#requestParams', 'url' => '/api/{apiVersion}/request-params', 'verb' => 'POST', 'requirements' => ['apiVersion' => '(v2)']], + ['name' => 'Settings#uploadedFiles', 'url' => '/api/{apiVersion}/uploaded-files', 'verb' => 'POST', 'requirements' => ['apiVersion' => '(v2)']], + ['name' => 'Settings#uploadedFileOnly', 'url' => '/api/{apiVersion}/uploaded-file-only', 'verb' => 'POST', 'requirements' => ['apiVersion' => '(v2)']], ['name' => 'Settings#publicPageAnnotation', 'url' => '/api/{apiVersion}/public-page/annotation', 'verb' => 'POST', 'requirements' => ['apiVersion' => '(v2)']], ['name' => 'Settings#publicPageAttribute', 'url' => '/api/{apiVersion}/public-page/attribute', 'verb' => 'POST', 'requirements' => ['apiVersion' => '(v2)']], ['name' => 'Settings#mergedResponses', 'url' => '/api/{apiVersion}/merged-responses', 'verb' => 'POST', 'requirements' => ['apiVersion' => '(v2)']], diff --git a/tests/lib/Controller/SettingsController.php b/tests/lib/Controller/SettingsController.php index 823ff05..634b7a8 100644 --- a/tests/lib/Controller/SettingsController.php +++ b/tests/lib/Controller/SettingsController.php @@ -797,6 +797,35 @@ public function requestParams(): DataResponse { return new DataResponse(); } + /** + * A method with uploaded files and a parameter + * + * @param string $name Name of the upload + * @return DataResponse, array{}> + * + * 200: Files uploaded + */ + public function uploadedFiles(string $name): DataResponse { + $this->request->getUploadedFile('file'); + $this->request->getUploadedFile('attachment'); + $this->request->getUploadedFile('file'); + + return new DataResponse(); + } + + /** + * A method with only an uploaded file + * + * @return DataResponse, array{}> + * + * 200: File uploaded + */ + public function uploadedFileOnly(): DataResponse { + $this->request->getUploadedFile('file'); + + return new DataResponse(); + } + /** * A public page with annotation. * diff --git a/tests/openapi-administration.json b/tests/openapi-administration.json index be6d8db..73f4cc3 100644 --- a/tests/openapi-administration.json +++ b/tests/openapi-administration.json @@ -8977,6 +8977,319 @@ } } }, + "/ocs/v2.php/apps/notifications/api/{apiVersion}/uploaded-files": { + "post": { + "operationId": "settings-uploaded-files", + "summary": "A method with uploaded files and a parameter", + "description": "This endpoint requires admin access", + "tags": [ + "settings" + ], + "security": [ + { + "bearer_auth": [] + }, + { + "basic_auth": [] + } + ], + "requestBody": { + "required": true, + "content": { + "application/json": { + "schema": { + "type": "object", + "required": [ + "name" + ], + "properties": { + "name": { + "type": "string", + "description": "Name of the upload" + } + } + } + }, + "multipart/form-data": { + "schema": { + "type": "object", + "required": [ + "name" + ], + "properties": { + "name": { + "type": "string", + "description": "Name of the upload" + }, + "file": { + "type": "string", + "format": "binary" + }, + "attachment": { + "type": "string", + "format": "binary" + } + } + } + } + } + }, + "parameters": [ + { + "name": "apiVersion", + "in": "path", + "required": true, + "schema": { + "type": "string", + "enum": [ + "v2" + ], + "default": "v2" + } + }, + { + "name": "OCS-APIRequest", + "in": "header", + "description": "Required to be true for the API request to pass", + "required": true, + "schema": { + "type": "boolean", + "default": true + } + } + ], + "responses": { + "200": { + "description": "Files uploaded", + "content": { + "application/json": { + "schema": { + "type": "object", + "required": [ + "ocs" + ], + "properties": { + "ocs": { + "type": "object", + "required": [ + "meta", + "data" + ], + "properties": { + "meta": { + "$ref": "#/components/schemas/OCSMeta" + }, + "data": {} + } + } + } + } + } + } + }, + "401": { + "description": "Current user is not logged in", + "content": { + "application/json": { + "schema": { + "type": "object", + "required": [ + "ocs" + ], + "properties": { + "ocs": { + "type": "object", + "required": [ + "meta", + "data" + ], + "properties": { + "meta": { + "$ref": "#/components/schemas/OCSMeta" + }, + "data": {} + } + } + } + } + } + } + }, + "403": { + "description": "Logged in account must be an admin", + "content": { + "application/json": { + "schema": { + "type": "object", + "required": [ + "ocs" + ], + "properties": { + "ocs": { + "type": "object", + "required": [ + "meta", + "data" + ], + "properties": { + "meta": { + "$ref": "#/components/schemas/OCSMeta" + }, + "data": {} + } + } + } + } + } + } + } + } + } + }, + "/ocs/v2.php/apps/notifications/api/{apiVersion}/uploaded-file-only": { + "post": { + "operationId": "settings-uploaded-file-only", + "summary": "A method with only an uploaded file", + "description": "This endpoint requires admin access", + "tags": [ + "settings" + ], + "security": [ + { + "bearer_auth": [] + }, + { + "basic_auth": [] + } + ], + "requestBody": { + "required": false, + "content": { + "multipart/form-data": { + "schema": { + "type": "object", + "properties": { + "file": { + "type": "string", + "format": "binary" + } + } + } + } + } + }, + "parameters": [ + { + "name": "apiVersion", + "in": "path", + "required": true, + "schema": { + "type": "string", + "enum": [ + "v2" + ], + "default": "v2" + } + }, + { + "name": "OCS-APIRequest", + "in": "header", + "description": "Required to be true for the API request to pass", + "required": true, + "schema": { + "type": "boolean", + "default": true + } + } + ], + "responses": { + "200": { + "description": "File uploaded", + "content": { + "application/json": { + "schema": { + "type": "object", + "required": [ + "ocs" + ], + "properties": { + "ocs": { + "type": "object", + "required": [ + "meta", + "data" + ], + "properties": { + "meta": { + "$ref": "#/components/schemas/OCSMeta" + }, + "data": {} + } + } + } + } + } + } + }, + "401": { + "description": "Current user is not logged in", + "content": { + "application/json": { + "schema": { + "type": "object", + "required": [ + "ocs" + ], + "properties": { + "ocs": { + "type": "object", + "required": [ + "meta", + "data" + ], + "properties": { + "meta": { + "$ref": "#/components/schemas/OCSMeta" + }, + "data": {} + } + } + } + } + } + } + }, + "403": { + "description": "Logged in account must be an admin", + "content": { + "application/json": { + "schema": { + "type": "object", + "required": [ + "ocs" + ], + "properties": { + "ocs": { + "type": "object", + "required": [ + "meta", + "data" + ], + "properties": { + "meta": { + "$ref": "#/components/schemas/OCSMeta" + }, + "data": {} + } + } + } + } + } + } + } + } + } + }, "/ocs/v2.php/apps/notifications/api/{apiVersion}/merged-responses": { "post": { "operationId": "settings-merged-responses", diff --git a/tests/openapi-full.json b/tests/openapi-full.json index ff82345..f9da52d 100644 --- a/tests/openapi-full.json +++ b/tests/openapi-full.json @@ -9177,6 +9177,319 @@ } } }, + "/ocs/v2.php/apps/notifications/api/{apiVersion}/uploaded-files": { + "post": { + "operationId": "settings-uploaded-files", + "summary": "A method with uploaded files and a parameter", + "description": "This endpoint requires admin access", + "tags": [ + "settings" + ], + "security": [ + { + "bearer_auth": [] + }, + { + "basic_auth": [] + } + ], + "requestBody": { + "required": true, + "content": { + "application/json": { + "schema": { + "type": "object", + "required": [ + "name" + ], + "properties": { + "name": { + "type": "string", + "description": "Name of the upload" + } + } + } + }, + "multipart/form-data": { + "schema": { + "type": "object", + "required": [ + "name" + ], + "properties": { + "name": { + "type": "string", + "description": "Name of the upload" + }, + "file": { + "type": "string", + "format": "binary" + }, + "attachment": { + "type": "string", + "format": "binary" + } + } + } + } + } + }, + "parameters": [ + { + "name": "apiVersion", + "in": "path", + "required": true, + "schema": { + "type": "string", + "enum": [ + "v2" + ], + "default": "v2" + } + }, + { + "name": "OCS-APIRequest", + "in": "header", + "description": "Required to be true for the API request to pass", + "required": true, + "schema": { + "type": "boolean", + "default": true + } + } + ], + "responses": { + "200": { + "description": "Files uploaded", + "content": { + "application/json": { + "schema": { + "type": "object", + "required": [ + "ocs" + ], + "properties": { + "ocs": { + "type": "object", + "required": [ + "meta", + "data" + ], + "properties": { + "meta": { + "$ref": "#/components/schemas/OCSMeta" + }, + "data": {} + } + } + } + } + } + } + }, + "401": { + "description": "Current user is not logged in", + "content": { + "application/json": { + "schema": { + "type": "object", + "required": [ + "ocs" + ], + "properties": { + "ocs": { + "type": "object", + "required": [ + "meta", + "data" + ], + "properties": { + "meta": { + "$ref": "#/components/schemas/OCSMeta" + }, + "data": {} + } + } + } + } + } + } + }, + "403": { + "description": "Logged in account must be an admin", + "content": { + "application/json": { + "schema": { + "type": "object", + "required": [ + "ocs" + ], + "properties": { + "ocs": { + "type": "object", + "required": [ + "meta", + "data" + ], + "properties": { + "meta": { + "$ref": "#/components/schemas/OCSMeta" + }, + "data": {} + } + } + } + } + } + } + } + } + } + }, + "/ocs/v2.php/apps/notifications/api/{apiVersion}/uploaded-file-only": { + "post": { + "operationId": "settings-uploaded-file-only", + "summary": "A method with only an uploaded file", + "description": "This endpoint requires admin access", + "tags": [ + "settings" + ], + "security": [ + { + "bearer_auth": [] + }, + { + "basic_auth": [] + } + ], + "requestBody": { + "required": false, + "content": { + "multipart/form-data": { + "schema": { + "type": "object", + "properties": { + "file": { + "type": "string", + "format": "binary" + } + } + } + } + } + }, + "parameters": [ + { + "name": "apiVersion", + "in": "path", + "required": true, + "schema": { + "type": "string", + "enum": [ + "v2" + ], + "default": "v2" + } + }, + { + "name": "OCS-APIRequest", + "in": "header", + "description": "Required to be true for the API request to pass", + "required": true, + "schema": { + "type": "boolean", + "default": true + } + } + ], + "responses": { + "200": { + "description": "File uploaded", + "content": { + "application/json": { + "schema": { + "type": "object", + "required": [ + "ocs" + ], + "properties": { + "ocs": { + "type": "object", + "required": [ + "meta", + "data" + ], + "properties": { + "meta": { + "$ref": "#/components/schemas/OCSMeta" + }, + "data": {} + } + } + } + } + } + } + }, + "401": { + "description": "Current user is not logged in", + "content": { + "application/json": { + "schema": { + "type": "object", + "required": [ + "ocs" + ], + "properties": { + "ocs": { + "type": "object", + "required": [ + "meta", + "data" + ], + "properties": { + "meta": { + "$ref": "#/components/schemas/OCSMeta" + }, + "data": {} + } + } + } + } + } + } + }, + "403": { + "description": "Logged in account must be an admin", + "content": { + "application/json": { + "schema": { + "type": "object", + "required": [ + "ocs" + ], + "properties": { + "ocs": { + "type": "object", + "required": [ + "meta", + "data" + ], + "properties": { + "meta": { + "$ref": "#/components/schemas/OCSMeta" + }, + "data": {} + } + } + } + } + } + } + } + } + } + }, "/ocs/v2.php/apps/notifications/api/{apiVersion}/merged-responses": { "post": { "operationId": "settings-merged-responses", From 88666d793f78c63b73441b0a1d161627882e1521 Mon Sep 17 00:00:00 2001 From: Luis Amorim Date: Wed, 18 Nov 2026 09:18:06 -0300 Subject: [PATCH 2/3] feat: Add RequestFile attribute to describe uploaded files Detection of getUploadedFile() calls can not describe required files, several files (files[]), a field name that differs from the request key or files that are read outside of the controller method. The optional RequestFile attribute (requestKey, fieldName, multiple, required, indirect) covers these cases. It is read by name like RequestHeader and overrides the detected file with the same key. - Required files are added to the multipart required list and make the request body required. application/json is not offered then, as it can not carry a file. - Multiple files are documented as an array of binary strings, with minItems 1 when required. - Conflicting field names and invalid attribute arguments are reported. Closes #404 Signed-off-by: Luis Amorim --- CHANGELOG.md | 1 + generate-spec.php | 31 +- src/ControllerMethod.php | 95 +++- src/UploadedFile.php | 54 +++ tests/appinfo/routes.php | 3 + tests/lib/Controller/SettingsController.php | 50 +++ tests/openapi-administration.json | 457 ++++++++++++++++++++ tests/openapi-full.json | 457 ++++++++++++++++++++ 8 files changed, 1135 insertions(+), 13 deletions(-) create mode 100644 src/UploadedFile.php diff --git a/CHANGELOG.md b/CHANGELOG.md index 3d4943c..6661554 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -14,6 +14,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0 - Support backed enums (`enum Foo: string`/`enum Foo: int`) as OpenAPI types, resolved from their native parameter type hint - Support the built-in `SortDirection` enum from PHP 8.6 (unbacked, so its cases are mapped to the `'ASC'`/`'DESC'` strings) - Ignore controller method parameters typed as an injected service (e.g. `\OCP\IUser`) instead of requiring docs for them and listing them in the generated OpenAPI file +- Support the `RequestFile` attribute (`requestKey`, `fieldName`, `multiple`, `required`, `indirect`) to describe uploaded files that can not be detected from `getUploadedFile()` calls, e.g. required files, several files (`files[]`) or files read outside of the controller method ### Fixed - Clean whitespace in description fields diff --git a/generate-spec.php b/generate-spec.php index 108d2ad..e283aab 100755 --- a/generate-spec.php +++ b/generate-spec.php @@ -841,12 +841,21 @@ } } - $required = $requiredBodyParameters !== []; + $bodyParameterNames = array_map(static fn (ControllerMethodParameter $parameter): string => $parameter->name, $bodyParameters); + $requiredUploadedFiles = []; + foreach ($uploadedFiles as $uploadedFile) { + if (in_array($uploadedFile->fieldName, $bodyParameterNames, true)) { + Logger::error($route->name, 'Uploaded file field "' . $uploadedFile->fieldName . '" has the same name as a body parameter.'); + } + if ($uploadedFile->required) { + $requiredUploadedFiles[] = $uploadedFile->fieldName; + } + } $schema = [ 'type' => 'object', ]; - if ($required) { + if ($requiredBodyParameters !== []) { $schema['required'] = $requiredBodyParameters; } $schema['properties'] = []; @@ -855,18 +864,22 @@ } $content = []; - if ($bodyParameters !== []) { + // A JSON body can not carry a file, so it is not an alternative when a file is required. + if ($bodyParameters !== [] && $requiredUploadedFiles === []) { $content['application/json'] = [ 'schema' => $schema, ]; } if ($uploadedFiles !== []) { - $multipartSchema = $schema; + $multipartSchema = [ + 'type' => 'object', + ]; + if ($requiredBodyParameters !== [] || $requiredUploadedFiles !== []) { + $multipartSchema['required'] = array_values(array_unique(array_merge($requiredBodyParameters, $requiredUploadedFiles))); + } + $multipartSchema['properties'] = $schema['properties']; foreach ($uploadedFiles as $uploadedFile) { - $multipartSchema['properties'][$uploadedFile] = [ - 'type' => 'string', - 'format' => 'binary', - ]; + $multipartSchema['properties'][$uploadedFile->fieldName] = $uploadedFile->toSchema(); } $content['multipart/form-data'] = [ 'schema' => $multipartSchema, @@ -874,7 +887,7 @@ } $operation['requestBody'] = [ - 'required' => $required, + 'required' => $requiredBodyParameters !== [] || $requiredUploadedFiles !== [], 'content' => $content, ]; } diff --git a/src/ControllerMethod.php b/src/ControllerMethod.php index 2d75d17..93d8586 100644 --- a/src/ControllerMethod.php +++ b/src/ControllerMethod.php @@ -9,6 +9,7 @@ use PhpParser\Node\Arg; use PhpParser\Node\AttributeGroup; +use PhpParser\Node\Expr\ConstFetch; use PhpParser\Node\Expr\MethodCall; use PhpParser\Node\Expr\PropertyFetch; use PhpParser\Node\Expr\Variable; @@ -291,7 +292,7 @@ class ControllerMethod { * @param OpenApiType[] $returns * @param array $responseDescription * @param string[] $description - * @param list $uploadedFiles + * @param list $uploadedFiles */ public function __construct( public array $parameters, @@ -614,7 +615,8 @@ public static function parse(string $context, } $codeRequestHeaders = []; - $uploadedFiles = []; + /** @var array $codeUploadedFiles Request keys read with getUploadedFile() */ + $codeUploadedFiles = []; foreach ($nodeFinder->findInstanceOf($method->getStmts(), MethodCall::class) as $methodCall) { if ($methodCall->var instanceof PropertyFetch && $methodCall->var->var instanceof Variable @@ -666,7 +668,7 @@ public static function parse(string $context, continue; } - $uploadedFiles[] = $arg->value->value; + $codeUploadedFiles[$arg->value->value] = true; } } } @@ -727,7 +729,92 @@ public static function parse(string $context, Logger::error($context, 'Unused request header descriptions: ' . implode(', ', $unusedRequestHeaders)); } - return new ControllerMethod($parameters, $attributeRequestHeaders, $responses, $responseDescriptions, $methodDescription, $methodSummary, $isDeprecated, array_values(array_unique($uploadedFiles))); + $uploadedFiles = self::parseUploadedFiles($context, $method, array_map('strval', array_keys($codeUploadedFiles))); + + return new ControllerMethod($parameters, $attributeRequestHeaders, $responses, $responseDescriptions, $methodDescription, $methodSummary, $isDeprecated, $uploadedFiles); + } + + /** + * Combine the files detected with getUploadedFile() and the ones described with the RequestFile attribute. + * + * The attribute takes precedence over the detected file with the same request key. + * Use `indirect: true` for files that are read outside of the controller method. + * + * @param list $codeRequestKeys + * @return list + */ + private static function parseUploadedFiles(string $context, ClassMethod $method, array $codeRequestKeys): array { + $uploadedFiles = []; + foreach ($codeRequestKeys as $requestKey) { + $uploadedFiles[$requestKey] = new UploadedFile($requestKey, $requestKey); + } + + $attributeRequestKeys = []; + /** @var AttributeGroup $attrGroup */ + foreach ($method->attrGroups as $attrGroup) { + foreach ($attrGroup->attrs as $attr) { + if ($attr->name->getLast() !== 'RequestFile') { + continue; + } + + $args = []; + foreach ($attr->args as $key => $arg) { + $attrName = $arg->name?->name ?? match ($key) { + 0 => 'requestKey', + 1 => 'fieldName', + 2 => 'multiple', + 3 => 'required', + 4 => 'indirect', + default => Logger::panic($context, 'RequestFile has too many arguments.'), + }; + + if (array_key_exists($attrName, $args)) { + Logger::panic($context, 'The ' . $attrName . ' of RequestFile is set twice.'); + } + + $args[$attrName] = match ($attrName) { + 'requestKey', 'fieldName' => $arg->value instanceof String_ ? $arg->value->value : Logger::panic($context, 'The ' . $attrName . ' of RequestFile has to be a string literal.'), + 'multiple', 'required', 'indirect' => $arg->value instanceof ConstFetch && in_array(strtolower($arg->value->name->toString()), ['true', 'false'], true) + ? strtolower($arg->value->name->toString()) === 'true' + : Logger::panic($context, 'The ' . $attrName . ' of RequestFile has to be true or false.'), + default => Logger::panic($context, 'Unknown argument "' . $attrName . '" for RequestFile.'), + }; + } + + if (!isset($args['requestKey'])) { + Logger::panic($context, 'RequestFile needs a requestKey.'); + } + + $requestKey = $args['requestKey']; + $multiple = $args['multiple'] ?? false; + // PHP only fills the array form of an upload for fields that end with []. + $fieldName = $args['fieldName'] ?? ($multiple ? $requestKey . '[]' : $requestKey); + if (str_ends_with($fieldName, '[]') !== $multiple) { + Logger::warning($context, 'RequestFile "' . $requestKey . '": multiple has to match the [] suffix of the field name "' . $fieldName . '".'); + } + + if (array_key_exists($requestKey, $attributeRequestKeys)) { + Logger::error($context, 'Uploaded file "' . $requestKey . '" already documented.'); + } + $attributeRequestKeys[$requestKey] = true; + + if (!($args['indirect'] ?? false) && !in_array($requestKey, $codeRequestKeys, true)) { + Logger::error($context, 'Unused RequestFile for "' . $requestKey . '". Use indirect: true if the file is read outside of the controller method.'); + } + + $uploadedFiles[$requestKey] = new UploadedFile($requestKey, $fieldName, $multiple, $args['required'] ?? false); + } + } + + $fieldNames = []; + foreach ($uploadedFiles as $uploadedFile) { + if (array_key_exists($uploadedFile->fieldName, $fieldNames)) { + Logger::error($context, 'Uploaded files "' . $fieldNames[$uploadedFile->fieldName] . '" and "' . $uploadedFile->requestKey . '" use the same field name "' . $uploadedFile->fieldName . '".'); + } + $fieldNames[$uploadedFile->fieldName] = $uploadedFile->requestKey; + } + + return array_values($uploadedFiles); } private static function cleanHeaderName(string $header): string { diff --git a/src/UploadedFile.php b/src/UploadedFile.php new file mode 100644 index 0000000..19884fb --- /dev/null +++ b/src/UploadedFile.php @@ -0,0 +1,54 @@ + 'string', + 'format' => 'binary', + ]; + + if ($this->multiple) { + $schema = [ + 'type' => 'array', + 'items' => $file, + ]; + if ($this->required) { + // An empty array would not send any file part + $schema['minItems'] = 1; + } + + return $schema; + } + + return $file; + } +} diff --git a/tests/appinfo/routes.php b/tests/appinfo/routes.php index 4a01c00..3eec2bc 100644 --- a/tests/appinfo/routes.php +++ b/tests/appinfo/routes.php @@ -90,6 +90,9 @@ ['name' => 'Settings#requestParams', 'url' => '/api/{apiVersion}/request-params', 'verb' => 'POST', 'requirements' => ['apiVersion' => '(v2)']], ['name' => 'Settings#uploadedFiles', 'url' => '/api/{apiVersion}/uploaded-files', 'verb' => 'POST', 'requirements' => ['apiVersion' => '(v2)']], ['name' => 'Settings#uploadedFileOnly', 'url' => '/api/{apiVersion}/uploaded-file-only', 'verb' => 'POST', 'requirements' => ['apiVersion' => '(v2)']], + ['name' => 'Settings#uploadedFileRequired', 'url' => '/api/{apiVersion}/uploaded-file-required', 'verb' => 'POST', 'requirements' => ['apiVersion' => '(v2)']], + ['name' => 'Settings#uploadedFilesMultiple', 'url' => '/api/{apiVersion}/uploaded-files-multiple', 'verb' => 'POST', 'requirements' => ['apiVersion' => '(v2)']], + ['name' => 'Settings#uploadedFileIndirect', 'url' => '/api/{apiVersion}/uploaded-file-indirect', 'verb' => 'POST', 'requirements' => ['apiVersion' => '(v2)']], ['name' => 'Settings#publicPageAnnotation', 'url' => '/api/{apiVersion}/public-page/annotation', 'verb' => 'POST', 'requirements' => ['apiVersion' => '(v2)']], ['name' => 'Settings#publicPageAttribute', 'url' => '/api/{apiVersion}/public-page/attribute', 'verb' => 'POST', 'requirements' => ['apiVersion' => '(v2)']], ['name' => 'Settings#mergedResponses', 'url' => '/api/{apiVersion}/merged-responses', 'verb' => 'POST', 'requirements' => ['apiVersion' => '(v2)']], diff --git a/tests/lib/Controller/SettingsController.php b/tests/lib/Controller/SettingsController.php index 634b7a8..3fc9071 100644 --- a/tests/lib/Controller/SettingsController.php +++ b/tests/lib/Controller/SettingsController.php @@ -19,6 +19,7 @@ use OCP\AppFramework\Http\Attribute\OpenAPI; use OCP\AppFramework\Http\Attribute\PasswordConfirmationRequired; use OCP\AppFramework\Http\Attribute\PublicPage; +use OCP\AppFramework\Http\Attribute\RequestFile; use OCP\AppFramework\Http\Attribute\RequestHeader; use OCP\AppFramework\Http\DataResponse; use OCP\AppFramework\Http\JSONResponse; @@ -826,6 +827,55 @@ public function uploadedFileOnly(): DataResponse { return new DataResponse(); } + /** + * A method with a required file + * + * @return DataResponse, array{}> + * + * 200: File uploaded + */ + #[RequestFile('file', required: true)] + public function uploadedFileRequired(): DataResponse { + $this->request->getUploadedFile('file'); + + return new DataResponse(); + } + + /** + * A method with several files in PHP's array form + * + * @param string $name Name of the upload + * @return DataResponse, array{}> + * + * 200: Files uploaded + */ + #[RequestFile(requestKey: 'files', fieldName: 'files[]', multiple: true, required: true)] + public function uploadedFilesMultiple(string $name): DataResponse { + $files = $this->request->getUploadedFile('files'); + + return new DataResponse(); + } + + /** + * A method that reads the upload outside of the route method + * + * @return DataResponse, array{}> + * + * 200: File uploaded + */ + #[RequestFile(requestKey: 'avatar', multiple: false, required: true, indirect: true)] + #[RequestFile('attachments', multiple: true, indirect: true)] + public function uploadedFileIndirect(): DataResponse { + return $this->handleUpload(); + } + + private function handleUpload(): DataResponse { + $this->request->getUploadedFile('avatar'); + $this->request->getUploadedFile('attachments'); + + return new DataResponse(); + } + /** * A public page with annotation. * diff --git a/tests/openapi-administration.json b/tests/openapi-administration.json index 73f4cc3..8a49649 100644 --- a/tests/openapi-administration.json +++ b/tests/openapi-administration.json @@ -9290,6 +9290,463 @@ } } }, + "/ocs/v2.php/apps/notifications/api/{apiVersion}/uploaded-file-required": { + "post": { + "operationId": "settings-uploaded-file-required", + "summary": "A method with a required file", + "description": "This endpoint requires admin access", + "tags": [ + "settings" + ], + "security": [ + { + "bearer_auth": [] + }, + { + "basic_auth": [] + } + ], + "requestBody": { + "required": true, + "content": { + "multipart/form-data": { + "schema": { + "type": "object", + "required": [ + "file" + ], + "properties": { + "file": { + "type": "string", + "format": "binary" + } + } + } + } + } + }, + "parameters": [ + { + "name": "apiVersion", + "in": "path", + "required": true, + "schema": { + "type": "string", + "enum": [ + "v2" + ], + "default": "v2" + } + }, + { + "name": "OCS-APIRequest", + "in": "header", + "description": "Required to be true for the API request to pass", + "required": true, + "schema": { + "type": "boolean", + "default": true + } + } + ], + "responses": { + "200": { + "description": "File uploaded", + "content": { + "application/json": { + "schema": { + "type": "object", + "required": [ + "ocs" + ], + "properties": { + "ocs": { + "type": "object", + "required": [ + "meta", + "data" + ], + "properties": { + "meta": { + "$ref": "#/components/schemas/OCSMeta" + }, + "data": {} + } + } + } + } + } + } + }, + "401": { + "description": "Current user is not logged in", + "content": { + "application/json": { + "schema": { + "type": "object", + "required": [ + "ocs" + ], + "properties": { + "ocs": { + "type": "object", + "required": [ + "meta", + "data" + ], + "properties": { + "meta": { + "$ref": "#/components/schemas/OCSMeta" + }, + "data": {} + } + } + } + } + } + } + }, + "403": { + "description": "Logged in account must be an admin", + "content": { + "application/json": { + "schema": { + "type": "object", + "required": [ + "ocs" + ], + "properties": { + "ocs": { + "type": "object", + "required": [ + "meta", + "data" + ], + "properties": { + "meta": { + "$ref": "#/components/schemas/OCSMeta" + }, + "data": {} + } + } + } + } + } + } + } + } + } + }, + "/ocs/v2.php/apps/notifications/api/{apiVersion}/uploaded-files-multiple": { + "post": { + "operationId": "settings-uploaded-files-multiple", + "summary": "A method with several files in PHP's array form", + "description": "This endpoint requires admin access", + "tags": [ + "settings" + ], + "security": [ + { + "bearer_auth": [] + }, + { + "basic_auth": [] + } + ], + "requestBody": { + "required": true, + "content": { + "multipart/form-data": { + "schema": { + "type": "object", + "required": [ + "name", + "files[]" + ], + "properties": { + "name": { + "type": "string", + "description": "Name of the upload" + }, + "files[]": { + "type": "array", + "items": { + "type": "string", + "format": "binary" + }, + "minItems": 1 + } + } + } + } + } + }, + "parameters": [ + { + "name": "apiVersion", + "in": "path", + "required": true, + "schema": { + "type": "string", + "enum": [ + "v2" + ], + "default": "v2" + } + }, + { + "name": "OCS-APIRequest", + "in": "header", + "description": "Required to be true for the API request to pass", + "required": true, + "schema": { + "type": "boolean", + "default": true + } + } + ], + "responses": { + "200": { + "description": "Files uploaded", + "content": { + "application/json": { + "schema": { + "type": "object", + "required": [ + "ocs" + ], + "properties": { + "ocs": { + "type": "object", + "required": [ + "meta", + "data" + ], + "properties": { + "meta": { + "$ref": "#/components/schemas/OCSMeta" + }, + "data": {} + } + } + } + } + } + } + }, + "401": { + "description": "Current user is not logged in", + "content": { + "application/json": { + "schema": { + "type": "object", + "required": [ + "ocs" + ], + "properties": { + "ocs": { + "type": "object", + "required": [ + "meta", + "data" + ], + "properties": { + "meta": { + "$ref": "#/components/schemas/OCSMeta" + }, + "data": {} + } + } + } + } + } + } + }, + "403": { + "description": "Logged in account must be an admin", + "content": { + "application/json": { + "schema": { + "type": "object", + "required": [ + "ocs" + ], + "properties": { + "ocs": { + "type": "object", + "required": [ + "meta", + "data" + ], + "properties": { + "meta": { + "$ref": "#/components/schemas/OCSMeta" + }, + "data": {} + } + } + } + } + } + } + } + } + } + }, + "/ocs/v2.php/apps/notifications/api/{apiVersion}/uploaded-file-indirect": { + "post": { + "operationId": "settings-uploaded-file-indirect", + "summary": "A method that reads the upload outside of the route method", + "description": "This endpoint requires admin access", + "tags": [ + "settings" + ], + "security": [ + { + "bearer_auth": [] + }, + { + "basic_auth": [] + } + ], + "requestBody": { + "required": true, + "content": { + "multipart/form-data": { + "schema": { + "type": "object", + "required": [ + "avatar" + ], + "properties": { + "avatar": { + "type": "string", + "format": "binary" + }, + "attachments[]": { + "type": "array", + "items": { + "type": "string", + "format": "binary" + } + } + } + } + } + } + }, + "parameters": [ + { + "name": "apiVersion", + "in": "path", + "required": true, + "schema": { + "type": "string", + "enum": [ + "v2" + ], + "default": "v2" + } + }, + { + "name": "OCS-APIRequest", + "in": "header", + "description": "Required to be true for the API request to pass", + "required": true, + "schema": { + "type": "boolean", + "default": true + } + } + ], + "responses": { + "200": { + "description": "File uploaded", + "content": { + "application/json": { + "schema": { + "type": "object", + "required": [ + "ocs" + ], + "properties": { + "ocs": { + "type": "object", + "required": [ + "meta", + "data" + ], + "properties": { + "meta": { + "$ref": "#/components/schemas/OCSMeta" + }, + "data": {} + } + } + } + } + } + } + }, + "401": { + "description": "Current user is not logged in", + "content": { + "application/json": { + "schema": { + "type": "object", + "required": [ + "ocs" + ], + "properties": { + "ocs": { + "type": "object", + "required": [ + "meta", + "data" + ], + "properties": { + "meta": { + "$ref": "#/components/schemas/OCSMeta" + }, + "data": {} + } + } + } + } + } + } + }, + "403": { + "description": "Logged in account must be an admin", + "content": { + "application/json": { + "schema": { + "type": "object", + "required": [ + "ocs" + ], + "properties": { + "ocs": { + "type": "object", + "required": [ + "meta", + "data" + ], + "properties": { + "meta": { + "$ref": "#/components/schemas/OCSMeta" + }, + "data": {} + } + } + } + } + } + } + } + } + } + }, "/ocs/v2.php/apps/notifications/api/{apiVersion}/merged-responses": { "post": { "operationId": "settings-merged-responses", diff --git a/tests/openapi-full.json b/tests/openapi-full.json index f9da52d..aee1f62 100644 --- a/tests/openapi-full.json +++ b/tests/openapi-full.json @@ -9490,6 +9490,463 @@ } } }, + "/ocs/v2.php/apps/notifications/api/{apiVersion}/uploaded-file-required": { + "post": { + "operationId": "settings-uploaded-file-required", + "summary": "A method with a required file", + "description": "This endpoint requires admin access", + "tags": [ + "settings" + ], + "security": [ + { + "bearer_auth": [] + }, + { + "basic_auth": [] + } + ], + "requestBody": { + "required": true, + "content": { + "multipart/form-data": { + "schema": { + "type": "object", + "required": [ + "file" + ], + "properties": { + "file": { + "type": "string", + "format": "binary" + } + } + } + } + } + }, + "parameters": [ + { + "name": "apiVersion", + "in": "path", + "required": true, + "schema": { + "type": "string", + "enum": [ + "v2" + ], + "default": "v2" + } + }, + { + "name": "OCS-APIRequest", + "in": "header", + "description": "Required to be true for the API request to pass", + "required": true, + "schema": { + "type": "boolean", + "default": true + } + } + ], + "responses": { + "200": { + "description": "File uploaded", + "content": { + "application/json": { + "schema": { + "type": "object", + "required": [ + "ocs" + ], + "properties": { + "ocs": { + "type": "object", + "required": [ + "meta", + "data" + ], + "properties": { + "meta": { + "$ref": "#/components/schemas/OCSMeta" + }, + "data": {} + } + } + } + } + } + } + }, + "401": { + "description": "Current user is not logged in", + "content": { + "application/json": { + "schema": { + "type": "object", + "required": [ + "ocs" + ], + "properties": { + "ocs": { + "type": "object", + "required": [ + "meta", + "data" + ], + "properties": { + "meta": { + "$ref": "#/components/schemas/OCSMeta" + }, + "data": {} + } + } + } + } + } + } + }, + "403": { + "description": "Logged in account must be an admin", + "content": { + "application/json": { + "schema": { + "type": "object", + "required": [ + "ocs" + ], + "properties": { + "ocs": { + "type": "object", + "required": [ + "meta", + "data" + ], + "properties": { + "meta": { + "$ref": "#/components/schemas/OCSMeta" + }, + "data": {} + } + } + } + } + } + } + } + } + } + }, + "/ocs/v2.php/apps/notifications/api/{apiVersion}/uploaded-files-multiple": { + "post": { + "operationId": "settings-uploaded-files-multiple", + "summary": "A method with several files in PHP's array form", + "description": "This endpoint requires admin access", + "tags": [ + "settings" + ], + "security": [ + { + "bearer_auth": [] + }, + { + "basic_auth": [] + } + ], + "requestBody": { + "required": true, + "content": { + "multipart/form-data": { + "schema": { + "type": "object", + "required": [ + "name", + "files[]" + ], + "properties": { + "name": { + "type": "string", + "description": "Name of the upload" + }, + "files[]": { + "type": "array", + "items": { + "type": "string", + "format": "binary" + }, + "minItems": 1 + } + } + } + } + } + }, + "parameters": [ + { + "name": "apiVersion", + "in": "path", + "required": true, + "schema": { + "type": "string", + "enum": [ + "v2" + ], + "default": "v2" + } + }, + { + "name": "OCS-APIRequest", + "in": "header", + "description": "Required to be true for the API request to pass", + "required": true, + "schema": { + "type": "boolean", + "default": true + } + } + ], + "responses": { + "200": { + "description": "Files uploaded", + "content": { + "application/json": { + "schema": { + "type": "object", + "required": [ + "ocs" + ], + "properties": { + "ocs": { + "type": "object", + "required": [ + "meta", + "data" + ], + "properties": { + "meta": { + "$ref": "#/components/schemas/OCSMeta" + }, + "data": {} + } + } + } + } + } + } + }, + "401": { + "description": "Current user is not logged in", + "content": { + "application/json": { + "schema": { + "type": "object", + "required": [ + "ocs" + ], + "properties": { + "ocs": { + "type": "object", + "required": [ + "meta", + "data" + ], + "properties": { + "meta": { + "$ref": "#/components/schemas/OCSMeta" + }, + "data": {} + } + } + } + } + } + } + }, + "403": { + "description": "Logged in account must be an admin", + "content": { + "application/json": { + "schema": { + "type": "object", + "required": [ + "ocs" + ], + "properties": { + "ocs": { + "type": "object", + "required": [ + "meta", + "data" + ], + "properties": { + "meta": { + "$ref": "#/components/schemas/OCSMeta" + }, + "data": {} + } + } + } + } + } + } + } + } + } + }, + "/ocs/v2.php/apps/notifications/api/{apiVersion}/uploaded-file-indirect": { + "post": { + "operationId": "settings-uploaded-file-indirect", + "summary": "A method that reads the upload outside of the route method", + "description": "This endpoint requires admin access", + "tags": [ + "settings" + ], + "security": [ + { + "bearer_auth": [] + }, + { + "basic_auth": [] + } + ], + "requestBody": { + "required": true, + "content": { + "multipart/form-data": { + "schema": { + "type": "object", + "required": [ + "avatar" + ], + "properties": { + "avatar": { + "type": "string", + "format": "binary" + }, + "attachments[]": { + "type": "array", + "items": { + "type": "string", + "format": "binary" + } + } + } + } + } + } + }, + "parameters": [ + { + "name": "apiVersion", + "in": "path", + "required": true, + "schema": { + "type": "string", + "enum": [ + "v2" + ], + "default": "v2" + } + }, + { + "name": "OCS-APIRequest", + "in": "header", + "description": "Required to be true for the API request to pass", + "required": true, + "schema": { + "type": "boolean", + "default": true + } + } + ], + "responses": { + "200": { + "description": "File uploaded", + "content": { + "application/json": { + "schema": { + "type": "object", + "required": [ + "ocs" + ], + "properties": { + "ocs": { + "type": "object", + "required": [ + "meta", + "data" + ], + "properties": { + "meta": { + "$ref": "#/components/schemas/OCSMeta" + }, + "data": {} + } + } + } + } + } + } + }, + "401": { + "description": "Current user is not logged in", + "content": { + "application/json": { + "schema": { + "type": "object", + "required": [ + "ocs" + ], + "properties": { + "ocs": { + "type": "object", + "required": [ + "meta", + "data" + ], + "properties": { + "meta": { + "$ref": "#/components/schemas/OCSMeta" + }, + "data": {} + } + } + } + } + } + } + }, + "403": { + "description": "Logged in account must be an admin", + "content": { + "application/json": { + "schema": { + "type": "object", + "required": [ + "ocs" + ], + "properties": { + "ocs": { + "type": "object", + "required": [ + "meta", + "data" + ], + "properties": { + "meta": { + "$ref": "#/components/schemas/OCSMeta" + }, + "data": {} + } + } + } + } + } + } + } + } + } + }, "/ocs/v2.php/apps/notifications/api/{apiVersion}/merged-responses": { "post": { "operationId": "settings-merged-responses", From e6b86283eec3b5e93a93e2d49ccbbc5d7fc16f15 Mon Sep 17 00:00:00 2001 From: Luis Amorim Date: Wed, 18 Nov 2026 11:12:59 -0300 Subject: [PATCH 3/3] feat: Keep optional body parameters out of multipart when named like a file A route can take file references as JSON and the files themselves as multipart, with the same names (e.g. `array $files = []` and getUploadedFile('files')). The multipart body copied the JSON schema, so the object list was documented next to the binary file, or was replaced by it for an exact name match, which failed the generation. An optional body parameter named like an uploaded file field, ignoring a trailing `[]`, is now only part of the JSON body. A required parameter keeps its place in both bodies, and an exact name clash on it is still an error, because a file part can not fill it. Document the limits in the README: no "at least one file" constraint, no multipart-only fields and one form per request key. Signed-off-by: Luis Amorim --- CHANGELOG.md | 1 + README.md | 15 ++ generate-spec.php | 17 +- src/UploadedFile.php | 5 + tests/appinfo/routes.php | 1 + tests/lib/Controller/SettingsController.php | 17 ++ tests/openapi-administration.json | 193 ++++++++++++++++++++ tests/openapi-full.json | 193 ++++++++++++++++++++ 8 files changed, 438 insertions(+), 4 deletions(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index 6661554..b167100 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -15,6 +15,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0 - Support the built-in `SortDirection` enum from PHP 8.6 (unbacked, so its cases are mapped to the `'ASC'`/`'DESC'` strings) - Ignore controller method parameters typed as an injected service (e.g. `\OCP\IUser`) instead of requiring docs for them and listing them in the generated OpenAPI file - Support the `RequestFile` attribute (`requestKey`, `fieldName`, `multiple`, `required`, `indirect`) to describe uploaded files that can not be detected from `getUploadedFile()` calls, e.g. required files, several files (`files[]`) or files read outside of the controller method +- Optional body parameters with the same name as an uploaded file are only documented in the JSON body, so a route can accept file references as JSON and the files themselves as multipart ### Fixed - Clean whitespace in description fields diff --git a/README.md b/README.md index 7240fdc..251dc15 100644 --- a/README.md +++ b/README.md @@ -24,6 +24,21 @@ Afterward in your repository settings set the OpenAPI workflow to be required fo Checkout the OpenAPI tutorial at https://docs.nextcloud.com/server/latest/developer_manual/client_apis/OCS/ocs-openapi.html to see how you can use openapi-extractor. +### Uploaded files + +Files read with `$this->request->getUploadedFile('name')` are documented as optional binary properties of a `multipart/form-data` request body (POST routes only), next to the `application/json` body. Use the `RequestFile` attribute when the code alone is not enough: + +```php +#[RequestFile(requestKey: 'files', fieldName: 'files[]', multiple: true, required: true, indirect: true)] +``` + +- `multiple: true` documents several files. Without the attribute, a file is always documented as a single file. +- `required: true` marks the file as required. The JSON body is then not documented, because it can not carry a file. +- `indirect: true` is needed when the file is read outside of the controller method. +- An optional body parameter with the same name as an uploaded file field (ignoring a trailing `[]`) is only documented in the JSON body. A required one with the exact same name is an error. + +Not supported: requiring "at least one of several files", fields that only exist in the multipart body, and both `file` and `file[]` for the same request key. + ### 🐢 Performance Make sure that you have xdebug turned off when generating OpenAPI specs, otherwise it can take multiple minutes instead of seconds. diff --git a/generate-spec.php b/generate-spec.php index e283aab..ff1dc17 100755 --- a/generate-spec.php +++ b/generate-spec.php @@ -841,11 +841,20 @@ } } - $bodyParameterNames = array_map(static fn (ControllerMethodParameter $parameter): string => $parameter->name, $bodyParameters); $requiredUploadedFiles = []; + // Optional body parameters named like an uploaded file are only part of the JSON body. + $jsonOnlyParameterNames = []; foreach ($uploadedFiles as $uploadedFile) { - if (in_array($uploadedFile->fieldName, $bodyParameterNames, true)) { - Logger::error($route->name, 'Uploaded file field "' . $uploadedFile->fieldName . '" has the same name as a body parameter.'); + foreach ($bodyParameters as $bodyParameter) { + if ($bodyParameter->name !== $uploadedFile->fieldName && $bodyParameter->name !== $uploadedFile->getBaseFieldName()) { + continue; + } + + if ($bodyParameter->type->nullable || $bodyParameter->type->hasDefaultValue) { + $jsonOnlyParameterNames[] = $bodyParameter->name; + } elseif ($bodyParameter->name === $uploadedFile->fieldName) { + Logger::error($route->name, 'Uploaded file field "' . $uploadedFile->fieldName . '" has the same name as a required body parameter.'); + } } if ($uploadedFile->required) { $requiredUploadedFiles[] = $uploadedFile->fieldName; @@ -877,7 +886,7 @@ if ($requiredBodyParameters !== [] || $requiredUploadedFiles !== []) { $multipartSchema['required'] = array_values(array_unique(array_merge($requiredBodyParameters, $requiredUploadedFiles))); } - $multipartSchema['properties'] = $schema['properties']; + $multipartSchema['properties'] = array_diff_key($schema['properties'], array_flip($jsonOnlyParameterNames)); foreach ($uploadedFiles as $uploadedFile) { $multipartSchema['properties'][$uploadedFile->fieldName] = $uploadedFile->toSchema(); } diff --git a/src/UploadedFile.php b/src/UploadedFile.php index 19884fb..8588cac 100644 --- a/src/UploadedFile.php +++ b/src/UploadedFile.php @@ -27,6 +27,11 @@ public function __construct( ) { } + /** The name PHP uses for the field, without the `[]` of the array form. */ + public function getBaseFieldName(): string { + return str_ends_with($this->fieldName, '[]') ? substr($this->fieldName, 0, -2) : $this->fieldName; + } + /** * @return array{type: 'string', format: 'binary'}|array{type: 'array', items: array{type: 'string', format: 'binary'}, minItems?: 1} */ diff --git a/tests/appinfo/routes.php b/tests/appinfo/routes.php index 3eec2bc..b0498e4 100644 --- a/tests/appinfo/routes.php +++ b/tests/appinfo/routes.php @@ -90,6 +90,7 @@ ['name' => 'Settings#requestParams', 'url' => '/api/{apiVersion}/request-params', 'verb' => 'POST', 'requirements' => ['apiVersion' => '(v2)']], ['name' => 'Settings#uploadedFiles', 'url' => '/api/{apiVersion}/uploaded-files', 'verb' => 'POST', 'requirements' => ['apiVersion' => '(v2)']], ['name' => 'Settings#uploadedFileOnly', 'url' => '/api/{apiVersion}/uploaded-file-only', 'verb' => 'POST', 'requirements' => ['apiVersion' => '(v2)']], + ['name' => 'Settings#uploadedFilesOrReferences', 'url' => '/api/{apiVersion}/uploaded-files-or-references', 'verb' => 'POST', 'requirements' => ['apiVersion' => '(v2)']], ['name' => 'Settings#uploadedFileRequired', 'url' => '/api/{apiVersion}/uploaded-file-required', 'verb' => 'POST', 'requirements' => ['apiVersion' => '(v2)']], ['name' => 'Settings#uploadedFilesMultiple', 'url' => '/api/{apiVersion}/uploaded-files-multiple', 'verb' => 'POST', 'requirements' => ['apiVersion' => '(v2)']], ['name' => 'Settings#uploadedFileIndirect', 'url' => '/api/{apiVersion}/uploaded-file-indirect', 'verb' => 'POST', 'requirements' => ['apiVersion' => '(v2)']], diff --git a/tests/lib/Controller/SettingsController.php b/tests/lib/Controller/SettingsController.php index 3fc9071..4612627 100644 --- a/tests/lib/Controller/SettingsController.php +++ b/tests/lib/Controller/SettingsController.php @@ -827,6 +827,23 @@ public function uploadedFileOnly(): DataResponse { return new DataResponse(); } + /** + * A method that takes file references as JSON or the files themselves as multipart + * + * @param array{id?: int} $file Reference to a file + * @param list $files References to files + * @param string $name Name of the upload + * @return DataResponse, array{}> + * + * 200: Files uploaded + */ + #[RequestFile('files', multiple: true)] + public function uploadedFilesOrReferences(array $file = [], array $files = [], string $name = ''): DataResponse { + $this->request->getUploadedFile('files') ?: $this->request->getUploadedFile('file'); + + return new DataResponse(); + } + /** * A method with a required file * diff --git a/tests/openapi-administration.json b/tests/openapi-administration.json index 8a49649..c0d7c2a 100644 --- a/tests/openapi-administration.json +++ b/tests/openapi-administration.json @@ -9290,6 +9290,199 @@ } } }, + "/ocs/v2.php/apps/notifications/api/{apiVersion}/uploaded-files-or-references": { + "post": { + "operationId": "settings-uploaded-files-or-references", + "summary": "A method that takes file references as JSON or the files themselves as multipart", + "description": "This endpoint requires admin access", + "tags": [ + "settings" + ], + "security": [ + { + "bearer_auth": [] + }, + { + "basic_auth": [] + } + ], + "requestBody": { + "required": false, + "content": { + "application/json": { + "schema": { + "type": "object", + "properties": { + "file": { + "type": "object", + "default": {}, + "description": "Reference to a file", + "properties": { + "id": { + "type": "integer", + "format": "int64" + } + } + }, + "files": { + "type": "array", + "default": [], + "description": "References to files", + "items": { + "type": "object", + "properties": { + "id": { + "type": "integer", + "format": "int64" + } + } + } + }, + "name": { + "type": "string", + "default": "", + "description": "Name of the upload" + } + } + } + }, + "multipart/form-data": { + "schema": { + "type": "object", + "properties": { + "name": { + "type": "string", + "default": "", + "description": "Name of the upload" + }, + "files[]": { + "type": "array", + "items": { + "type": "string", + "format": "binary" + } + }, + "file": { + "type": "string", + "format": "binary" + } + } + } + } + } + }, + "parameters": [ + { + "name": "apiVersion", + "in": "path", + "required": true, + "schema": { + "type": "string", + "enum": [ + "v2" + ], + "default": "v2" + } + }, + { + "name": "OCS-APIRequest", + "in": "header", + "description": "Required to be true for the API request to pass", + "required": true, + "schema": { + "type": "boolean", + "default": true + } + } + ], + "responses": { + "200": { + "description": "Files uploaded", + "content": { + "application/json": { + "schema": { + "type": "object", + "required": [ + "ocs" + ], + "properties": { + "ocs": { + "type": "object", + "required": [ + "meta", + "data" + ], + "properties": { + "meta": { + "$ref": "#/components/schemas/OCSMeta" + }, + "data": {} + } + } + } + } + } + } + }, + "401": { + "description": "Current user is not logged in", + "content": { + "application/json": { + "schema": { + "type": "object", + "required": [ + "ocs" + ], + "properties": { + "ocs": { + "type": "object", + "required": [ + "meta", + "data" + ], + "properties": { + "meta": { + "$ref": "#/components/schemas/OCSMeta" + }, + "data": {} + } + } + } + } + } + } + }, + "403": { + "description": "Logged in account must be an admin", + "content": { + "application/json": { + "schema": { + "type": "object", + "required": [ + "ocs" + ], + "properties": { + "ocs": { + "type": "object", + "required": [ + "meta", + "data" + ], + "properties": { + "meta": { + "$ref": "#/components/schemas/OCSMeta" + }, + "data": {} + } + } + } + } + } + } + } + } + } + }, "/ocs/v2.php/apps/notifications/api/{apiVersion}/uploaded-file-required": { "post": { "operationId": "settings-uploaded-file-required", diff --git a/tests/openapi-full.json b/tests/openapi-full.json index aee1f62..9a77c29 100644 --- a/tests/openapi-full.json +++ b/tests/openapi-full.json @@ -9490,6 +9490,199 @@ } } }, + "/ocs/v2.php/apps/notifications/api/{apiVersion}/uploaded-files-or-references": { + "post": { + "operationId": "settings-uploaded-files-or-references", + "summary": "A method that takes file references as JSON or the files themselves as multipart", + "description": "This endpoint requires admin access", + "tags": [ + "settings" + ], + "security": [ + { + "bearer_auth": [] + }, + { + "basic_auth": [] + } + ], + "requestBody": { + "required": false, + "content": { + "application/json": { + "schema": { + "type": "object", + "properties": { + "file": { + "type": "object", + "default": {}, + "description": "Reference to a file", + "properties": { + "id": { + "type": "integer", + "format": "int64" + } + } + }, + "files": { + "type": "array", + "default": [], + "description": "References to files", + "items": { + "type": "object", + "properties": { + "id": { + "type": "integer", + "format": "int64" + } + } + } + }, + "name": { + "type": "string", + "default": "", + "description": "Name of the upload" + } + } + } + }, + "multipart/form-data": { + "schema": { + "type": "object", + "properties": { + "name": { + "type": "string", + "default": "", + "description": "Name of the upload" + }, + "files[]": { + "type": "array", + "items": { + "type": "string", + "format": "binary" + } + }, + "file": { + "type": "string", + "format": "binary" + } + } + } + } + } + }, + "parameters": [ + { + "name": "apiVersion", + "in": "path", + "required": true, + "schema": { + "type": "string", + "enum": [ + "v2" + ], + "default": "v2" + } + }, + { + "name": "OCS-APIRequest", + "in": "header", + "description": "Required to be true for the API request to pass", + "required": true, + "schema": { + "type": "boolean", + "default": true + } + } + ], + "responses": { + "200": { + "description": "Files uploaded", + "content": { + "application/json": { + "schema": { + "type": "object", + "required": [ + "ocs" + ], + "properties": { + "ocs": { + "type": "object", + "required": [ + "meta", + "data" + ], + "properties": { + "meta": { + "$ref": "#/components/schemas/OCSMeta" + }, + "data": {} + } + } + } + } + } + } + }, + "401": { + "description": "Current user is not logged in", + "content": { + "application/json": { + "schema": { + "type": "object", + "required": [ + "ocs" + ], + "properties": { + "ocs": { + "type": "object", + "required": [ + "meta", + "data" + ], + "properties": { + "meta": { + "$ref": "#/components/schemas/OCSMeta" + }, + "data": {} + } + } + } + } + } + } + }, + "403": { + "description": "Logged in account must be an admin", + "content": { + "application/json": { + "schema": { + "type": "object", + "required": [ + "ocs" + ], + "properties": { + "ocs": { + "type": "object", + "required": [ + "meta", + "data" + ], + "properties": { + "meta": { + "$ref": "#/components/schemas/OCSMeta" + }, + "data": {} + } + } + } + } + } + } + } + } + } + }, "/ocs/v2.php/apps/notifications/api/{apiVersion}/uploaded-file-required": { "post": { "operationId": "settings-uploaded-file-required",