feat: emit a canonical OpenAPI document covering every SDK platform

The Specs task writes open-api3-<version>.json alongside the per-platform files: every route any platform offers, every method alias variant, all response models, the union of tags and of security schemes. The generator selects a platform from x-appwrite.platforms since 4.8.0; what it could not select was x-appwrite.auth, whose value differs per platform, so the canonical document keys auth by platform and each security scheme lists the platforms whose SDK offers it. The per-platform documents are unchanged apart from that scheme-level platforms list, which is why they stay byte-identical for the SDKs generated from them.

Related to CLO-4377.
This commit is contained in:
Chirag Aggarwal committed 2026-09-07 11:04:23 +01:00
1 parent 4729c7ba45
commit dcadf3d795
4 files changed
+255 -69

No files matched your search

+28 -21
View File
@@ -458,10 +458,16 @@ class Specs extends Action
$specsContainer->set('localeCodes', fn () => \array_map(fn ($locale) => $locale['code'], Config::getParam('locale-codes', [])));
$specsContainer->set('plan', fn () => []);
$platforms = static::getPlatforms();
$platforms = \array_values(static::getPlatforms());
$authCounts = $this->getAuthCounts();
$keys = $this->getKeys();
$platformKeys = $this->getKeys();
$keys = [];
foreach ($platforms as $platform) {
$keys[$platform] = $platformKeys[$platform] ?? [];
}
/** @var array<string, string|null> $generatedFiles Spec file path to its platform, null for the canonical document. */
$generatedFiles = [];
$endpoint = System::getEnv('_APP_HOME', 'https://appwrite.io');
$email = System::getEnv('_APP_SYSTEM_TEAM_EMAIL', 'team@appwrite.io');
@@ -483,7 +489,8 @@ class Specs extends Action
}
}
foreach ($platforms as $platform) {
// One document per platform, then the canonical document (null) covering every platform.
foreach ([...$platforms, null] as $platform) {
$routes = [];
$models = [];
$services = [];
@@ -506,7 +513,9 @@ class Specs extends Action
}
foreach ($sdks as $sdk) {
if (!\in_array($platform, $sdk->getPlatforms(), true)) {
$sdkPlatforms = $sdk->getPlatforms();
if ($platform === null ? $sdkPlatforms === [] : !\in_array($platform, $sdkPlatforms, true)) {
continue;
}
@@ -541,8 +550,9 @@ class Specs extends Action
continue;
}
// Check if current platform is included in service's platforms
if (!\in_array($platform, $service['platforms'] ?? [])) {
$servicePlatforms = $service['platforms'] ?? [];
if ($platform === null ? \array_intersect($servicePlatforms, $platforms) === [] : !\in_array($platform, $servicePlatforms)) {
continue;
}
@@ -573,7 +583,7 @@ class Specs extends Action
$models = $response->getModels();
foreach ($models as $key => $value) {
if ($platform !== APP_SDK_PLATFORM_CONSOLE && !$value->isPublic()) {
if ($platform !== null && $platform !== APP_SDK_PLATFORM_CONSOLE && !$value->isPublic()) {
unset($models[$key]);
}
}
@@ -583,8 +593,8 @@ class Specs extends Action
$services,
$routes,
$models,
$keys[$platform],
$authCounts[$platform] ?? 0,
$keys,
$authCounts,
$platform,
];
@@ -609,15 +619,16 @@ class Specs extends Action
->setParam('docs.description', 'Full API docs, specs and tutorials')
->setParam('docs.url', $endpoint . '/docs');
$suffix = $platform === null ? '' : '-' . $platform;
$path = $mocks
? $specsDir . '/' . $format . '-mocks-' . $platform . '.json'
: $specsDir . '/' . $format . '-' . $version . '-' . $platform . '.json';
? $specsDir . '/' . $format . '-mocks' . $suffix . '.json'
: $specsDir . '/' . $format . '-' . $version . $suffix . '.json';
try {
$parsedSpecs = $specs->parse();
} catch (\RuntimeException $e) {
// A throw is reported and carried on from, so stop here
Console::error("Spec generation failed for {$platform} ({$format}): " . $e->getMessage());
Console::error('Spec generation failed for ' . ($platform ?? 'canonical') . " ({$format}): " . $e->getMessage());
Console::exit(1);
return;
}
@@ -634,7 +645,7 @@ class Specs extends Action
throw new Exception('Failed to save ' . ($mocks ? 'mocks ' : '') . 'spec file: ' . $path);
}
$generatedFiles[] = realpath($path);
$generatedFiles[realpath($path)] = $platform;
Console::success('Saved ' . ($mocks ? 'mocks ' : '') . 'spec file: ' . realpath($path));
unset($encodedSpecs, $specs, $formatInstance);
@@ -668,16 +679,12 @@ class Specs extends Action
git reset --hard origin/' . $gitBranch . ' 2>/dev/null || true
');
// Copy generated spec files into specs/{version}/ subdirectory
// Copy the canonical document and the PR platforms' documents into specs/{version}/
$prPlatforms = static::getPlatformsForPR();
$prFiles = \array_filter(
$prFiles = \array_keys(\array_filter(
$generatedFiles,
fn (string $file) => \in_array(
\substr(\basename($file, '.json'), \strrpos(\basename($file, '.json'), '-') + 1),
$prPlatforms,
true
)
);
fn (?string $platform) => $platform === null || \in_array($platform, $prPlatforms, true)
));
$specsSubDir = $mocks ? 'mocks' : $version;
\exec('mkdir -p ' . \escapeshellarg("{$target}/specs/{$specsSubDir}"));
+45 -4
View File
@@ -22,9 +22,25 @@ abstract class Format
protected array $models;
protected array $services;
/**
* Security schemes per SDK platform, in `Specs::getPlatforms()` order.
*
* @var array<string, array<string, array<string, mixed>>>
*/
protected array $keys;
protected int $authCount;
protected string $platform;
/**
* Number of example credentials per SDK platform.
*
* @var array<string, int>
*/
protected array $authCounts;
/**
* Platform the document is filtered to, or null for the canonical document.
*/
protected ?string $platform;
protected array $params = [
'name' => '',
'description' => '',
@@ -41,17 +57,42 @@ abstract class Format
'license.url' => '',
];
public function __construct(Container $container, array $services, array $routes, array $models, array $keys, int $authCount, string $platform)
public function __construct(Container $container, array $services, array $routes, array $models, array $keys, array $authCounts, ?string $platform)
{
$this->container = $container;
$this->services = $services;
$this->routes = $routes;
$this->models = $models;
$this->keys = $keys;
$this->authCount = $authCount;
$this->authCounts = $authCounts;
$this->platform = $platform;
}
/**
* Security schemes of this document, each carrying the platforms whose SDK
* offers it: the platform's own schemes, or for the canonical document the
* union in platform order where the first definition wins.
*
* @return array<string, array<string, mixed>>
*/
protected function getSecuritySchemes(): array
{
$schemes = [];
foreach ($this->keys as $platform => $platformSchemes) {
if ($this->platform !== null && $platform !== $this->platform) {
continue;
}
foreach ($platformSchemes as $name => $scheme) {
$schemes[$name] ??= $scheme;
$schemes[$name]['x-appwrite']['platforms'][] = $platform;
}
}
return $schemes;
}
/**
* Get Name.
*
@@ -164,8 +164,40 @@ class OpenAPI3 extends Format
return \strtolower((string) \preg_replace('/[^a-z0-9]/i', '', $name));
}
/**
* The schemes an SDK example configures before calling a method: the first
* `authCount` accepted schemes offered on the platform, plus the path-bound
* schemes of a location method. Flat for a platform document; keyed by
* platform for the canonical document.
*
* @param array<string, list<string>> $securities
* @param list<string> $locationKeys
* @param list<string> $platforms
* @return array<string, mixed>
*/
private function getExampleAuth(array $securities, array $locationKeys, array $platforms): array
{
$auth = [];
foreach ($this->platform === null ? $platforms : [$this->platform] as $platform) {
$offered = \array_intersect_key($securities, $this->keys[$platform] ?? []);
$slice = \array_slice($offered, 0, $this->authCounts[$platform] ?? 0);
foreach ($locationKeys as $key) {
if (isset($this->keys[$platform][$key])) {
$slice[$key] = [];
}
}
$auth[$platform] = $slice;
}
return $this->platform === null ? $auth : ($auth[$this->platform] ?? []);
}
public function parse(): array
{
$schemes = $this->getSecuritySchemes();
/**
* Specifications (v3.0.0):
* https://github.com/OAI/OpenAPI-Specification/blob/master/versions/3.0.0.md
@@ -207,7 +239,7 @@ class OpenAPI3 extends Format
'tags' => $this->services,
'components' => [
'schemas' => [],
'securitySchemes' => $this->keys,
'securitySchemes' => $schemes,
],
'externalDocs' => [
'description' => $this->getParam('docs.description'),
@@ -249,7 +281,7 @@ class OpenAPI3 extends Format
$sdkPlatforms = \array_merge($sdkPlatforms, $method->getPlatforms());
}
$sdkPlatforms = \array_values(\array_unique($sdkPlatforms));
if (!\in_array($this->platform, $sdkPlatforms, true)) {
if ($this->platform === null ? $sdkPlatforms === [] : !\in_array($this->platform, $sdkPlatforms, true)) {
continue;
}
@@ -308,13 +340,13 @@ class OpenAPI3 extends Format
$methodSdkPlatforms = $methodObj->getPlatforms();
if (!\in_array($this->platform, $methodSdkPlatforms, true)) {
if ($this->platform === null ? $methodSdkPlatforms === [] : !\in_array($this->platform, $methodSdkPlatforms, true)) {
continue;
}
$methodSecurities = [($methodObj->getLocationAuth()[0] ?? 'Project') => []];
foreach ($methodObj->getAuth() as $security) {
if (\array_key_exists($security->value, $this->keys)) {
if (\array_key_exists($security->value, $schemes)) {
$methodSecurities[$security->value] = [];
}
}
@@ -324,7 +356,7 @@ class OpenAPI3 extends Format
'namespace' => $methodObj->getNamespace(),
'platforms' => $methodSdkPlatforms,
'desc' => $methodObj->getDesc(),
'auth' => \array_slice($methodSecurities, 0, $this->authCount),
'auth' => $this->getExampleAuth($methodSecurities, [], $methodSdkPlatforms),
'parameters' => [],
'required' => [],
'responses' => [],
@@ -532,20 +564,18 @@ class OpenAPI3 extends Format
foreach ($sdk->getAuth() as $security) {
/** @var AuthType $security */
if (array_key_exists($security->value, $this->keys)) {
if (\array_key_exists($security->value, $schemes)) {
$securities[$security->value] = [];
}
}
$temp['x-appwrite']['auth'] = array_slice($securities, 0, $this->authCount);
$locationKeys = $sdk->getType() === MethodType::LOCATION
? \array_values(\array_filter($sdk->getLocationAuth(), fn (string $key) => \array_key_exists($key, $schemes)))
: [];
$temp['x-appwrite']['auth'] = $this->getExampleAuth($securities, $locationKeys, $sdkPlatforms);
if ($sdk->getType() === MethodType::LOCATION) {
foreach ($sdk->getLocationAuth() as $key) {
if (\array_key_exists($key, $this->keys)) {
$securities[$key] = [];
$temp['x-appwrite']['auth'][$key] = [];
}
}
foreach ($locationKeys as $key) {
$securities[$key] = [];
}
$temp['security'][] = $securities;
+138 -30
View File
@@ -124,7 +124,7 @@ final class FormatTest extends TestCase
{
parent::setUp();
$this->format = new TestFormat(new Container(), [], [], [], [], 0, 'console');
$this->format = new TestFormat(new Container(), [], [], [], [], ['console' => 0], 'console');
}
public function testProjectRequestParameterOverrides(): void
@@ -182,7 +182,7 @@ final class FormatTest extends TestCase
new ArrayList(new Text(255), 10),
]), 'Metric names.', false, enum: new Enum(name: 'TestMetric'));
$spec = (new OpenAPI3(new Container(), [], [$route], [], [], 0, 'console'))->parse();
$spec = (new OpenAPI3(new Container(), [], [$route], [], [], ['console' => 0], 'console'))->parse();
$this->assertSame([
'type' => 'string',
@@ -220,7 +220,7 @@ final class FormatTest extends TestCase
map: ['basic' => 'Basic', 'advanced' => 'Advanced'],
));
$spec = (new OpenAPI3(new Container(), [], [$route], [], [], 0, 'console'))->parse();
$spec = (new OpenAPI3(new Container(), [], [$route], [], [], ['console' => 0], 'console'))->parse();
$kind = $spec['paths']['/tests']['post']['requestBody']['content']['application/json']['schema']['properties']['kind'];
$this->assertSame('TestKind', $kind['title']);
@@ -256,7 +256,7 @@ final class FormatTest extends TestCase
[$route],
[],
[],
0,
['console' => 0],
'console',
);
@@ -282,7 +282,7 @@ final class FormatTest extends TestCase
responses: [new SDKResponse(code: Response::STATUS_CODE_OK, model: Response::MODEL_HEALTH_STATUS)],
));
$spec = (new OpenAPI3(new Container(), [], [$route], [new HealthStatus()], [], 0, 'console'))->parse();
$spec = (new OpenAPI3(new Container(), [], [$route], [new HealthStatus()], [], ['console' => 0], 'console'))->parse();
$status = $spec['components']['schemas']['healthStatus']['properties']['status'];
$this->assertSame('HealthCheckStatus', $status['title']);
@@ -312,7 +312,7 @@ final class FormatTest extends TestCase
))
->param('userId', '', new CustomId(), 'User ID.');
$spec = (new OpenAPI3(new Container(), [], [$route], [], [], 0, 'console'))->parse();
$spec = (new OpenAPI3(new Container(), [], [$route], [], [], ['console' => 0], 'console'))->parse();
$userId = $spec['paths']['/tests']['post']['requestBody']['content']['application/json']['schema']['properties']['userId'];
@@ -344,7 +344,7 @@ final class FormatTest extends TestCase
->param('enabled', false, new BooleanValidator(true), 'Enabled.', example: 'true')
->param('text', '', new Text(64), 'Text.', example: '["one","two"]');
$spec = (new OpenAPI3(new Container(), [], [$route], [], [], 0, 'console'))->parse();
$spec = (new OpenAPI3(new Container(), [], [$route], [], [], ['console' => 0], 'console'))->parse();
$properties = $spec['paths']['/tests']['post']['requestBody']['content']['application/json']['schema']['properties'];
$this->assertEquals((object) ['enabled' => true], $properties['metadata']['example']);
@@ -376,7 +376,7 @@ final class FormatTest extends TestCase
->param('labels', [], new ArrayList(new Text(16)), 'Labels.', optional: true)
->param('values', [], new ArrayList(new MixedValidator()), 'Values.', optional: true);
$spec = (new OpenAPI3(new Container(), [], [$route], [], [], 0, 'console'))->parse();
$spec = (new OpenAPI3(new Container(), [], [$route], [], [], ['console' => 0], 'console'))->parse();
$properties = $spec['paths']['/tests']['post']['requestBody']['content']['application/json']['schema']['properties'];
$this->assertSame(['type' => 'number', 'format' => 'double'], $properties['percents']['items']);
@@ -408,7 +408,7 @@ final class FormatTest extends TestCase
->param('name', '', new Text(128), 'Original description.')
->param('engine', 'mysql', new Text(16), 'Engine.', true);
$spec = (new OpenAPI3(new Container(), [], [$route], [], [], 0, 'console'))->parse();
$spec = (new OpenAPI3(new Container(), [], [$route], [], [], ['console' => 0], 'console'))->parse();
$properties = $spec['paths']['/tests']['post']['requestBody']['content']['application/json']['schema']['properties'];
@@ -440,7 +440,7 @@ final class FormatTest extends TestCase
->param('name', 'default-name', new Text(128), 'Original description.', true)
->param('engine', 'mysql', new Text(16), 'Engine.', true);
$format = new class (new Container(), [], [], [], [], 0, 'console') extends OpenAPI3 {
$format = new class (new Container(), [], [], [], [], ['console' => 0], 'console') extends OpenAPI3 {
/**
* @return array<string, array<string, mixed>>
*/
@@ -477,7 +477,7 @@ final class FormatTest extends TestCase
->param('testId', '', new Text(256), 'Test ID.')
->param('transactionId', null, new Nullable(new Text(256)), 'Transaction ID.', true);
$openApi = (new OpenAPI3(new Container(), [], [$route], [], [], 0, 'console'))->parse();
$openApi = (new OpenAPI3(new Container(), [], [$route], [], [], ['console' => 0], 'console'))->parse();
$this->assertArrayNotHasKey('requestBody', $openApi['paths']['/tests/{testId}']['delete']);
$this->assertCount(2, $openApi['paths']['/tests/{testId}']['delete']['parameters']);
@@ -510,7 +510,7 @@ final class FormatTest extends TestCase
->param('testId', '', new Text(256), 'Test ID.')
->param('name', null, new Nullable(new Text(256)), 'Test name.', true);
$openApi = (new OpenAPI3(new Container(), [], [$route], [], [], 0, 'console'))->parse();
$openApi = (new OpenAPI3(new Container(), [], [$route], [], [], ['console' => 0], 'console'))->parse();
$get = $openApi['paths']['/tests/{testId}']['get'];
$post = $openApi['paths']['/tests/{testId}']['post'];
@@ -552,7 +552,7 @@ final class FormatTest extends TestCase
new ErrorModel(),
];
$openApi = (new OpenAPI3(new Container(), [], [$route], $models, [], 0, 'console'))->parse();
$openApi = (new OpenAPI3(new Container(), [], [$route], $models, [], ['console' => 0], 'console'))->parse();
$openApiPrefs = $openApi['components']['schemas']['team']['properties']['prefs'];
@@ -624,7 +624,7 @@ final class FormatTest extends TestCase
],
));
$openApi = (new OpenAPI3(new Container(), [], [$route], [$parent, $child], [], 0, 'console'))->parse();
$openApi = (new OpenAPI3(new Container(), [], [$route], [$parent, $child], [], ['console' => 0], 'console'))->parse();
$property = $openApi['components']['schemas']['parentWithoutExample']['properties']['child'];
$this->assertSame('object', $property['type']);
@@ -652,7 +652,7 @@ final class FormatTest extends TestCase
],
));
$openApi = (new OpenAPI3(new Container(), [], [$route], [new ErrorDev()], [], 0, 'console'))->parse();
$openApi = (new OpenAPI3(new Container(), [], [$route], [new ErrorDev()], [], ['console' => 0], 'console'))->parse();
$trace = $openApi['components']['schemas']['errorDev']['properties']['trace'];
$this->assertSame('array', $trace['type']);
@@ -679,7 +679,7 @@ final class FormatTest extends TestCase
->param('sessionId', 'current', new Text(256), 'Session ID.', true)
->param('filter', '', new Text(256), 'Optional query filter.', true);
$openApi = (new OpenAPI3(new Container(), [], [$route], [new NoneModel()], [], 0, 'console'))->parse();
$openApi = (new OpenAPI3(new Container(), [], [$route], [new NoneModel()], [], ['console' => 0], 'console'))->parse();
$parameters = [];
foreach ($openApi['paths']['/tests/{sessionId}']['get']['parameters'] as $parameter) {
@@ -727,7 +727,7 @@ final class FormatTest extends TestCase
new ErrorModel(),
];
$openApi = (new OpenAPI3(new Container(), [], [$route], $models, [], 0, 'console'))->parse();
$openApi = (new OpenAPI3(new Container(), [], [$route], $models, [], ['console' => 0], 'console'))->parse();
$properties = $openApi['components']['schemas']['usageProject']['properties'];
@@ -765,7 +765,7 @@ final class FormatTest extends TestCase
],
));
$openApi = (new OpenAPI3(new Container(), [], [$route], [new Migration()], [], 0, 'console'))->parse();
$openApi = (new OpenAPI3(new Container(), [], [$route], [new Migration()], [], ['console' => 0], 'console'))->parse();
$resourceData = $openApi['components']['schemas']['migration']['properties']['resourceData'];
$this->assertSame('array', $resourceData['type']);
@@ -844,7 +844,7 @@ final class FormatTest extends TestCase
new AlgoMd5(),
];
$openApi = (new OpenAPI3(new Container(), [], [$route], $models, [], 0, 'console'))->parse();
$openApi = (new OpenAPI3(new Container(), [], [$route], $models, [], ['console' => 0], 'console'))->parse();
$openApiHashOptions = $openApi['components']['schemas']['user']['properties']['hashOptions'];
@@ -890,7 +890,7 @@ final class FormatTest extends TestCase
],
));
$openApi = (new OpenAPI3(new Container(), [], [$requestRoute, $modelRoute], [new AttributeLine()], [], 0, 'console'))->parse();
$openApi = (new OpenAPI3(new Container(), [], [$requestRoute, $modelRoute], [new AttributeLine()], [], ['console' => 0], 'console'))->parse();
$openApiRequestDefault = $openApi['paths']['/tests/spatial']['post']['requestBody']['content']['application/json']['schema']['properties']['default'];
$openApiModelDefault = $openApi['components']['schemas']['attributeLine']['properties']['default'];
@@ -929,7 +929,7 @@ final class FormatTest extends TestCase
->param('nullablePassword', null, new Nullable(new PasswordFormat(new Text(256, 0))), 'Nullable password.', true)
->param('name', '', new Text(256), 'Name.');
$openApi = (new OpenAPI3(new Container(), [], [$route], [new Webhook()], [], 0, 'console'))->parse();
$openApi = (new OpenAPI3(new Container(), [], [$route], [new Webhook()], [], ['console' => 0], 'console'))->parse();
$openApiProperties = $openApi['paths']['/tests']['post']['requestBody']['content']['application/json']['schema']['properties'];
@@ -970,7 +970,7 @@ final class FormatTest extends TestCase
))
->param('testId', '', new Text(256), 'Test ID.');
$openApi = (new OpenAPI3(new Container(), [], [$route], [new NoneModel()], [], 0, 'console'))->parse();
$openApi = (new OpenAPI3(new Container(), [], [$route], [new NoneModel()], [], ['console' => 0], 'console'))->parse();
$openApiMethod = $openApi['paths']['/tests/{testId}']['delete'];
@@ -1007,7 +1007,7 @@ final class FormatTest extends TestCase
contentType: $contentType,
));
$openApi = (new OpenAPI3(new Container(), [], [$route], [new NoneModel()], [], 0, 'console'))->parse();
$openApi = (new OpenAPI3(new Container(), [], [$route], [new NoneModel()], [], ['console' => 0], 'console'))->parse();
$openApiMethod = $openApi['paths']['/tests/file']['get'];
@@ -1042,7 +1042,7 @@ final class FormatTest extends TestCase
],
));
$openApi = (new OpenAPI3(new Container(), [], [$route], [], [], 0, 'console'))->parse();
$openApi = (new OpenAPI3(new Container(), [], [$route], [], [], ['console' => 0], 'console'))->parse();
$openApiQuery = $openApi['paths']['/tests/graphql']['post']['requestBody']['content']['application/json']['schema']['properties']['query'];
@@ -1104,7 +1104,7 @@ final class FormatTest extends TestCase
));
}
$openApi = (new OpenAPI3(new Container(), [], $routes, $models, [], 0, 'console'))->parse();
$openApi = (new OpenAPI3(new Container(), [], $routes, $models, [], ['console' => 0], 'console'))->parse();
$openApiOptions = $openApi['components']['schemas']['provider']['properties']['options'];
@@ -1147,7 +1147,7 @@ final class FormatTest extends TestCase
->param('repositoryQueries', [], new VcsRepositories(), 'Repository queries.', true)
->param('deepQueries', [], $deepSubclass, 'Deeply nested queries.', true);
$openApi = (new OpenAPI3(new Container(), [], [$route], [], [], 0, 'console'))->parse();
$openApi = (new OpenAPI3(new Container(), [], [$route], [], [], ['console' => 0], 'console'))->parse();
$parameters = $openApi['paths']['/tests/queries']['get']['parameters'];
$schemas = \array_column($parameters, 'schema', 'name');
@@ -1178,7 +1178,7 @@ final class FormatTest extends TestCase
->param('min', 0, new Range(0, 100), 'Minimum.', example: '0')
->param('label', '', new Text(64), 'Label.', example: '0');
$spec = (new OpenAPI3(new Container(), [], [$route], [], [], 0, 'console'))->parse();
$spec = (new OpenAPI3(new Container(), [], [$route], [], [], ['console' => 0], 'console'))->parse();
$properties = $spec['paths']['/tests']['post']['requestBody']['content']['application/json']['schema']['properties'];
// "0" is falsy, so a truthiness check silently discards it and falls back
@@ -1208,7 +1208,7 @@ final class FormatTest extends TestCase
->param('domain', '', new Domain(), 'Domain name.')
->param('background', '', new HexColor(), 'Background colour.');
$spec = (new OpenAPI3(new Container(), [], [$route], [], [], 0, 'console'))->parse();
$spec = (new OpenAPI3(new Container(), [], [$route], [], [], ['console' => 0], 'console'))->parse();
$properties = $spec['paths']['/tests']['post']['requestBody']['content']['application/json']['schema']['properties'];
// Without a case of their own these validators fell through to the
@@ -1242,7 +1242,7 @@ final class FormatTest extends TestCase
],
);
$methods = $this->sdkMethods((new OpenAPI3(new Container(), [], [$route], [], [], 0, 'console'))->parse());
$methods = $this->sdkMethods((new OpenAPI3(new Container(), [], [$route], [], [], ['console' => 0], 'console'))->parse());
$this->assertContains('transactionId', $methods['createDocument']);
$this->assertContains('transactionId', $methods['createDocuments']);
@@ -1268,7 +1268,7 @@ final class FormatTest extends TestCase
],
);
$methods = $this->sdkMethods((new OpenAPI3(new Container(), [], [$route], [], [], 0, 'console'))->parse());
$methods = $this->sdkMethods((new OpenAPI3(new Container(), [], [$route], [], [], ['console' => 0], 'console'))->parse());
$this->assertNotContains('transactionId', $methods['createDocument']);
$this->assertNotContains('transactionId', $methods['createDocuments']);
@@ -1278,6 +1278,114 @@ final class FormatTest extends TestCase
* @param list<Parameter> $createDocument
* @param list<Parameter> $createDocuments
*/
public function testCanonicalDocumentKeysExampleAuthByPlatform(): void
{
Method::$processed = [];
Method::$errors = [];
$route = (new Route('GET', '/v1/account'))
->desc('Get account')
->label('scope', 'account')
->label('sdk', new Method(
namespace: 'account',
group: null,
name: 'get',
description: 'Get account.',
auth: [AuthType::SESSION, AuthType::KEY, AuthType::ADMIN],
responses: [],
));
$keys = $this->platformKeys();
$authCounts = ['client' => 1, 'server' => 2, 'console' => 1];
$canonical = (new OpenAPI3(new Container(), [], [$route], [], $keys, $authCounts, null))->parse();
$server = (new OpenAPI3(new Container(), [], [$route], [], $keys, $authCounts, 'server'))->parse();
$operation = $canonical['paths']['/account']['get'];
$this->assertSame(['client', 'server', 'console'], $operation['x-appwrite']['platforms']);
$this->assertSame([
'client' => ['Project' => []],
'server' => ['Project' => [], 'Session' => []],
'console' => ['Project' => []],
], $operation['x-appwrite']['auth']);
$this->assertSame(['Project' => [], 'Session' => [], 'Key' => []], $operation['security'][0]);
$this->assertSame(['Project' => [], 'Session' => []], $server['paths']['/account']['get']['x-appwrite']['auth']);
$this->assertSame(['Project' => [], 'Session' => [], 'Key' => []], $server['paths']['/account']['get']['security'][0]);
$this->assertSame(['Project', 'Session', 'Key'], \array_keys($canonical['components']['securitySchemes']));
$this->assertSame(['client', 'server', 'console'], $canonical['components']['securitySchemes']['Project']['x-appwrite']['platforms']);
$this->assertSame(['server'], $canonical['components']['securitySchemes']['Key']['x-appwrite']['platforms']);
$this->assertSame(['Project', 'Key', 'Session'], \array_keys($server['components']['securitySchemes']));
$this->assertSame(['server'], $server['components']['securitySchemes']['Key']['x-appwrite']['platforms']);
}
public function testCanonicalDocumentListsEveryAliasVariant(): void
{
Method::$processed = [];
Method::$errors = [];
$route = (new Route('PATCH', '/v1/presences/:presenceId'))
->desc('Update presence')
->label('scope', 'presence')
->label('sdk', [
new Method(
namespace: 'presences',
group: null,
name: 'update',
description: 'Update presence.',
auth: [AuthType::SESSION],
responses: [],
parameters: [new Parameter('presenceId', optional: false)],
),
new Method(
namespace: 'presences',
group: null,
name: 'update',
description: 'Update presence for a user.',
auth: [AuthType::KEY],
responses: [],
parameters: [new Parameter('presenceId', optional: false), new Parameter('userId', optional: false)],
),
])
->param('presenceId', '', new Text(256), 'Presence ID.')
->param('userId', '', new Text(256), 'User ID.', true);
$keys = $this->platformKeys();
$authCounts = ['client' => 1, 'server' => 2, 'console' => 1];
$canonical = (new OpenAPI3(new Container(), [], [$route], [], $keys, $authCounts, null))->parse()['paths']['/presences/{presenceId}']['patch'];
$client = (new OpenAPI3(new Container(), [], [$route], [], $keys, $authCounts, 'client'))->parse()['paths']['/presences/{presenceId}']['patch'];
$this->assertSame(['client', 'server'], $canonical['x-appwrite']['platforms']);
$this->assertCount(2, $canonical['x-appwrite']['methods']);
$this->assertSame(['client'], $canonical['x-appwrite']['methods'][0]['platforms']);
$this->assertSame(['client' => ['Project' => []]], $canonical['x-appwrite']['methods'][0]['auth']);
$this->assertSame(['presenceId'], $canonical['x-appwrite']['methods'][0]['required']);
$this->assertSame(['server'], $canonical['x-appwrite']['methods'][1]['platforms']);
$this->assertSame(['server' => ['Project' => [], 'Key' => []]], $canonical['x-appwrite']['methods'][1]['auth']);
$this->assertSame(['presenceId', 'userId'], $canonical['x-appwrite']['methods'][1]['required']);
$this->assertCount(1, $client['x-appwrite']['methods']);
$this->assertSame(['Project' => []], $client['x-appwrite']['methods'][0]['auth']);
}
/**
* @return array<string, array<string, array<string, mixed>>>
*/
private function platformKeys(): array
{
$project = ['type' => 'apiKey', 'name' => 'X-Appwrite-Project', 'in' => 'header'];
$session = ['type' => 'apiKey', 'name' => 'X-Appwrite-Session', 'in' => 'header'];
$key = ['type' => 'apiKey', 'name' => 'X-Appwrite-Key', 'in' => 'header'];
return [
'client' => ['Project' => $project, 'Session' => $session],
'server' => ['Project' => $project, 'Key' => $key, 'Session' => $session],
'console' => ['Project' => $project],
];
}
private function createDocumentsRoute(array $createDocument, array $createDocuments): Route
{
return (new Route('POST', '/v1/documentsdb/:databaseId/collections/:collectionId/documents'))