mirror of
https://github.com/appwrite/appwrite.git
synced 2026-11-18 20:36:03 +00:00
fix(specs): keep open enums open in the generated spec (#13295)
* fix(specs): keep open enums open in the generated spec A param declared as `AnyOf([WhiteList(...), Text(...)])` accepts any string at runtime — the whitelist names the values callers usually want and the text branch keeps everything else valid. The formatter resolved such a union by taking `getValidators()[0]` and discarding the rest, so the text branch never reached the spec. Paired with an `enum:` declaration the result advertises a closed set for a param that is deliberately open, and generated SDKs then reject values the endpoint would have accepted. Emit the union the way OpenAPI already expresses it, with `anyOf` over the enum branch and a plain string branch. That mirrors the validator exactly, so a generator can widen the parameter type while still offering the enum for discovery, and it needs no new vendor extension — the enum branch carries the same `x-enum-name` / `x-enum-keys` it does today. Strictness is derived from the validator rather than declared separately, so it cannot drift from what the endpoint actually accepts — that drift is what produced the wrong spec in the first place. No committed spec changes: the union is only emitted when an open union also declares an enum, and no param in this repository does both. * refactor(specs): simplify open enum handling * test(specs): focus open enum coverage
This commit is contained in:
1 parent
eeeaba89cc
commit
46e8cc7bba
2 files changed
+84
-1
No files matched your search
@@ -23,6 +23,7 @@ use Utopia\Validator;
|
||||
use Utopia\Validator\ArrayList;
|
||||
use Utopia\Validator\Nullable;
|
||||
use Utopia\Validator\Range;
|
||||
use Utopia\Validator\WhiteList;
|
||||
|
||||
class OpenAPI3 extends Format
|
||||
{
|
||||
@@ -533,9 +534,22 @@ class OpenAPI3 extends Format
|
||||
$class = Queries::class;
|
||||
}
|
||||
|
||||
$openEnum = false;
|
||||
if ($class === \Utopia\Validator\AnyOf::class) {
|
||||
$validator = $param['validator']->getValidators()[0];
|
||||
$validators = $param['validator']->getValidators();
|
||||
$validator = $validators[0];
|
||||
$class = \get_class($validator);
|
||||
|
||||
foreach ($validators as $unionValidator) {
|
||||
while ($unionValidator instanceof ArrayList || $unionValidator instanceof Nullable) {
|
||||
$unionValidator = $unionValidator->getValidator();
|
||||
}
|
||||
|
||||
if (!$unionValidator instanceof WhiteList && $unionValidator->getType() === Validator::TYPE_STRING) {
|
||||
$openEnum = true;
|
||||
break;
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
$array = false;
|
||||
@@ -754,6 +768,15 @@ class OpenAPI3 extends Format
|
||||
$node['schema']['items']['x-enum-name'] = $enum->name;
|
||||
}
|
||||
$node['schema']['items']['x-enum-keys'] = $enumKeys;
|
||||
|
||||
if ($openEnum) {
|
||||
$node['schema']['items'] = [
|
||||
'anyOf' => [
|
||||
$node['schema']['items'],
|
||||
['type' => Validator::TYPE_STRING],
|
||||
],
|
||||
];
|
||||
}
|
||||
}
|
||||
}
|
||||
if ($validator->getType() === 'integer') {
|
||||
@@ -791,6 +814,26 @@ class OpenAPI3 extends Format
|
||||
$node['schema']['x-enum-name'] = $enum->name;
|
||||
}
|
||||
$node['schema']['x-enum-keys'] = $enumKeys;
|
||||
|
||||
if ($openEnum) {
|
||||
$enumBranch = ['type' => $node['schema']['type'], 'enum' => $enumValues];
|
||||
if (!empty($enum->name)) {
|
||||
$enumBranch['x-enum-name'] = $enum->name;
|
||||
}
|
||||
$enumBranch['x-enum-keys'] = $enumKeys;
|
||||
|
||||
unset(
|
||||
$node['schema']['type'],
|
||||
$node['schema']['enum'],
|
||||
$node['schema']['x-enum-name'],
|
||||
$node['schema']['x-enum-keys'],
|
||||
);
|
||||
|
||||
$node['schema']['anyOf'] = [
|
||||
$enumBranch,
|
||||
['type' => Validator::TYPE_STRING],
|
||||
];
|
||||
}
|
||||
}
|
||||
}
|
||||
if ($validator->getType() === 'integer') {
|
||||
@@ -937,6 +980,13 @@ class OpenAPI3 extends Format
|
||||
$body['content'][$consumes[0]]['schema']['properties'][$name]['format'] = $node['schema']['format'];
|
||||
}
|
||||
|
||||
if (isset($node['schema']['anyOf'])) {
|
||||
// Open enum: the known values and the free-form branch
|
||||
// both live under anyOf, so copy the union wholesale.
|
||||
$body['content'][$consumes[0]]['schema']['properties'][$name]['anyOf'] = $node['schema']['anyOf'];
|
||||
unset($body['content'][$consumes[0]]['schema']['properties'][$name]['type']);
|
||||
}
|
||||
|
||||
if (isset($node['schema']['enum'])) {
|
||||
/// If the enum flag is Set, add the enum values to the body
|
||||
$body['content'][$consumes[0]]['schema']['properties'][$name]['enum'] = $node['schema']['enum'];
|
||||
|
||||
@@ -47,6 +47,8 @@ use Utopia\Database\Validator\Query\Offset;
|
||||
use Utopia\Database\Validator\Spatial;
|
||||
use Utopia\DI\Container;
|
||||
use Utopia\Http\Route;
|
||||
use Utopia\Platform\Enum;
|
||||
use Utopia\Validator\AnyOf;
|
||||
use Utopia\Validator\ArrayList;
|
||||
use Utopia\Validator\Assoc;
|
||||
use Utopia\Validator\Boolean as BooleanValidator;
|
||||
@@ -54,6 +56,7 @@ use Utopia\Validator\JSON;
|
||||
use Utopia\Validator\Nullable;
|
||||
use Utopia\Validator\Range;
|
||||
use Utopia\Validator\Text;
|
||||
use Utopia\Validator\WhiteList;
|
||||
|
||||
class TestFormat extends Format
|
||||
{
|
||||
@@ -124,6 +127,36 @@ final class FormatTest extends TestCase
|
||||
$this->assertSame('HealthCheckStatus', (new HealthStatus())->getRules()['status']['enumSDKName']);
|
||||
}
|
||||
|
||||
public function testUnionWithAFreeStringBranchEmitsAnyOf(): void
|
||||
{
|
||||
Method::$processed = [];
|
||||
Method::$errors = [];
|
||||
|
||||
$route = (new Route('GET', '/v1/tests'))
|
||||
->desc('List tests')
|
||||
->label('sdk', new Method(
|
||||
namespace: 'test',
|
||||
group: null,
|
||||
name: 'listTests',
|
||||
description: 'List tests.',
|
||||
auth: [],
|
||||
responses: [],
|
||||
))
|
||||
->param('metrics', [], new AnyOf([
|
||||
new ArrayList(new WhiteList(['alpha', 'beta'], true), 10),
|
||||
new ArrayList(new Text(255), 10),
|
||||
]), 'Metric names.', false, enum: new Enum(name: 'TestMetric'));
|
||||
|
||||
$spec = (new OpenAPI3(new Container(), [], [$route], [], [], 0, 'console'))->parse();
|
||||
|
||||
$this->assertSame([
|
||||
'anyOf' => [
|
||||
['type' => 'string', 'enum' => ['alpha', 'beta'], 'x-enum-name' => 'TestMetric', 'x-enum-keys' => ['alpha', 'beta']],
|
||||
['type' => 'string'],
|
||||
],
|
||||
], $spec['paths']['/tests']['get']['parameters'][0]['schema']['items']);
|
||||
}
|
||||
|
||||
public function testOpenApiCustomIdBodyFieldIncludesIdGeneratorMetadata(): void
|
||||
{
|
||||
Method::$processed = [];
|
||||
|
||||
Reference in new issue
Block a user