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",