diff --git a/CHANGELOG.md b/CHANGELOG.md index 3d4943c..b167100 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -14,6 +14,8 @@ 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 +- 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 77d068c..ff1dc17 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) { @@ -834,12 +841,30 @@ } } - $required = $requiredBodyParameters !== []; + $requiredUploadedFiles = []; + // Optional body parameters named like an uploaded file are only part of the JSON body. + $jsonOnlyParameterNames = []; + foreach ($uploadedFiles as $uploadedFile) { + 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; + } + } $schema = [ 'type' => 'object', ]; - if ($required) { + if ($requiredBodyParameters !== []) { $schema['required'] = $requiredBodyParameters; } $schema['properties'] = []; @@ -847,13 +872,32 @@ $schema['properties'][$bodyParameter->name] = $bodyParameter->type->toArray($schemas); } + $content = []; + // 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 = [ + 'type' => 'object', + ]; + if ($requiredBodyParameters !== [] || $requiredUploadedFiles !== []) { + $multipartSchema['required'] = array_values(array_unique(array_merge($requiredBodyParameters, $requiredUploadedFiles))); + } + $multipartSchema['properties'] = array_diff_key($schema['properties'], array_flip($jsonOnlyParameterNames)); + foreach ($uploadedFiles as $uploadedFile) { + $multipartSchema['properties'][$uploadedFile->fieldName] = $uploadedFile->toSchema(); + } + $content['multipart/form-data'] = [ + 'schema' => $multipartSchema, + ]; + } + $operation['requestBody'] = [ - 'required' => $required, - 'content' => [ - 'application/json' => [ - 'schema' => $schema, - ], - ], + 'required' => $requiredBodyParameters !== [] || $requiredUploadedFiles !== [], + 'content' => $content, ]; } diff --git a/src/ControllerMethod.php b/src/ControllerMethod.php index e92a45c..93d8586 100644 --- a/src/ControllerMethod.php +++ b/src/ControllerMethod.php @@ -7,10 +7,13 @@ namespace OpenAPIExtractor; +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; +use PhpParser\Node\Scalar\String_; use PhpParser\Node\Stmt\ClassMethod; use PhpParser\Node\Stmt\Return_; use PHPStan\PhpDocParser\Ast\PhpDoc\DeprecatedTagValueNode; @@ -289,6 +292,7 @@ class ControllerMethod { * @param OpenApiType[] $returns * @param array $responseDescription * @param string[] $description + * @param list $uploadedFiles */ public function __construct( public array $parameters, @@ -298,6 +302,7 @@ public function __construct( public array $description, public ?string $summary, public bool $isDeprecated, + public array $uploadedFiles, ) { } @@ -610,6 +615,8 @@ public static function parse(string $context, } $codeRequestHeaders = []; + /** @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 @@ -654,6 +661,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; + } + + $codeUploadedFiles[$arg->value->value] = true; + } } } @@ -713,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); + $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..8588cac --- /dev/null +++ b/src/UploadedFile.php @@ -0,0 +1,59 @@ +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} + */ + public function toSchema(): array { + $file = [ + 'type' => '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 0ef05cd..b0498e4 100644 --- a/tests/appinfo/routes.php +++ b/tests/appinfo/routes.php @@ -88,6 +88,12 @@ ['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#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)']], ['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..4612627 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; @@ -797,6 +798,101 @@ 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 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 + * + * @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 be6d8db..c0d7c2a 100644 --- a/tests/openapi-administration.json +++ b/tests/openapi-administration.json @@ -8977,6 +8977,969 @@ } } }, + "/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}/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", + "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 ff82345..9a77c29 100644 --- a/tests/openapi-full.json +++ b/tests/openapi-full.json @@ -9177,6 +9177,969 @@ } } }, + "/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}/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", + "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",