Skip to content
Draft
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
2 changes: 2 additions & 0 deletions CHANGELOG.md
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down
15 changes: 15 additions & 0 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -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.
62 changes: 53 additions & 9 deletions generate-spec.php
Original file line number Diff line number Diff line change
Expand Up @@ -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) {
Expand All @@ -834,26 +841,63 @@
}
}

$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'] = [];
foreach ($bodyParameters as $bodyParameter) {
$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,
];
}

Expand Down
103 changes: 102 additions & 1 deletion src/ControllerMethod.php
Original file line number Diff line number Diff line change
Expand Up @@ -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;
Expand Down Expand Up @@ -289,6 +292,7 @@ class ControllerMethod {
* @param OpenApiType[] $returns
* @param array<int, string> $responseDescription
* @param string[] $description
* @param list<UploadedFile> $uploadedFiles
*/
public function __construct(
public array $parameters,
Expand All @@ -298,6 +302,7 @@ public function __construct(
public array $description,
public ?string $summary,
public bool $isDeprecated,
public array $uploadedFiles,
) {
}

Expand Down Expand Up @@ -610,6 +615,8 @@ public static function parse(string $context,
}

$codeRequestHeaders = [];
/** @var array<string, true> $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
Expand Down Expand Up @@ -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;
}
}
}

Expand Down Expand Up @@ -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<string> $codeRequestKeys
* @return list<UploadedFile>
*/
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 {
Expand Down
59 changes: 59 additions & 0 deletions src/UploadedFile.php
Original file line number Diff line number Diff line change
@@ -0,0 +1,59 @@
<?php

declare(strict_types=1);

/**
* SPDX-FileCopyrightText: 2026 Nextcloud GmbH and Nextcloud contributors
* SPDX-License-Identifier: AGPL-3.0-or-later
*/

namespace OpenAPIExtractor;

/**
* A file that is uploaded with a multipart/form-data request.
*/
class UploadedFile {
/**
* @param string $requestKey Key used to read the file from the request (`IRequest::getUploadedFile($requestKey)`)
* @param string $fieldName Name of the multipart field the client has to send, if it differs from the key (e.g. `files[]`)
* @param bool $multiple Whether the endpoint accepts several files in the field
* @param bool $required Whether the endpoint rejects requests without the file
*/
public function __construct(
public string $requestKey,
public string $fieldName,
public bool $multiple = false,
public bool $required = false,
) {
}

/** 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}
*/
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;
}
}
6 changes: 6 additions & 0 deletions tests/appinfo/routes.php
Original file line number Diff line number Diff line change
Expand Up @@ -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)']],
Expand Down
Loading