From 5453271705d896c80a84bdf1eb03bd1bed63f8d6 Mon Sep 17 00:00:00 2001 From: Chirag Aggarwal Date: Thu, 11 Jun 2026 10:46:24 +0530 Subject: [PATCH] Fix OpenAPI 3 spec generation parity with Swagger 2 (#12564) The OpenAPI 3 format generator dropped or diverged on several pieces of information that the Swagger 2 generator emits, so SDKs generated from the OpenAPI 3 specs differed from those generated from Swagger 2: - Deduplicate x-appwrite platforms with array_unique - Merge Method additionalParameters into route params (GraphQL routes lost their query/variables body parameters) - Emit the default {} for JSON/Assoc parameters on the schema - Always emit x-enum-keys for string whitelist enums, mirroring Swagger 2 - Emit response content for binary (Image/File) and redirect responses so the produced content type is preserved - Keep the produced content type in x-appwrite.produces when no response declares content (e.g. 204-only methods), and align the No content description with Swagger 2 for 204/301/302/308 - Mirror Swagger 2 for json model rules: keep additionalProperties: true (previously overwritten), skip nullable, and emit type object even for array json rules Verified by generating all SDKs from both spec formats across the console, client and server platforms: output is now byte-identical. --- .../SDK/Specification/Format/OpenAPI3.php | 79 +++++++--- tests/unit/SDK/Specification/FormatTest.php | 143 ++++++++++++++++++ 2 files changed, 201 insertions(+), 21 deletions(-) diff --git a/src/Appwrite/SDK/Specification/Format/OpenAPI3.php b/src/Appwrite/SDK/Specification/Format/OpenAPI3.php index b53f0b32e5..38f81bca69 100644 --- a/src/Appwrite/SDK/Specification/Format/OpenAPI3.php +++ b/src/Appwrite/SDK/Specification/Format/OpenAPI3.php @@ -129,6 +129,7 @@ class OpenAPI3 extends Format $specs = new Specs(); $sdkPlatforms = $specs->getSDKPlatformsForRouteSecurity($routeSecurity); + $sdkPlatforms = array_values(array_unique($sdkPlatforms)); $namespace = $sdk->getNamespace(); $descContents = $this->getDescriptionContents($desc); @@ -323,6 +324,17 @@ class OpenAPI3 extends Format 'image/bmp', ]) ? 'Image' : 'File', ]; + + if ($produces !== '') { + $temp['responses'][(string)$response->getCode()]['content'] = [ + $produces => [ + 'schema' => [ + 'type' => 'string', + 'format' => 'binary', + ], + ], + ]; + } } else { if (\is_array($model)) { $modelDescription = \join(', or ', \array_map(fn ($m) => $m->getName(), $model)); @@ -359,12 +371,29 @@ class OpenAPI3 extends Format } } - if ($response->getCode() === 204) { + if (in_array($response->getCode(), [204, 301, 302, 308], true)) { $temp['responses'][(string)$response->getCode()]['description'] = 'No content'; + } + + if ($response->getCode() === 204) { unset($temp['responses'][(string)$response->getCode()]['content']); } } + // No response declares content (e.g. 204 No content): keep the produced + // content type available for SDK generation. + $hasResponseContent = false; + foreach ($temp['responses'] as $responseData) { + if (isset($responseData['content'])) { + $hasResponseContent = true; + break; + } + } + + if (!$hasResponseContent && $produces !== '') { + $temp['x-appwrite']['produces'] = [$produces]; + } + if (!empty($scope)) { $securities = [($sdk->getLocationAuth()[0] ?? 'Project') => []]; @@ -402,7 +431,12 @@ class OpenAPI3 extends Format $bodyRequired = []; - foreach ($route->getParams() as $name => $param) { // Set params + $parameters = \array_merge( + $route->getParams(), + $sdk->getAdditionalParameters(), + ); + + foreach ($parameters as $name => $param) { // Set params if (($param['deprecated'] ?? false) === true) { continue; } @@ -548,8 +582,8 @@ class OpenAPI3 extends Format break; case \Utopia\Validator\JSON::class: case \Utopia\Validator\Assoc::class: - $param['default'] = (empty($param['default'])) ? new \stdClass() : $param['default']; $node['schema']['type'] = 'object'; + $node['schema']['default'] = (empty($param['default'])) ? new \stdClass() : $param['default']; $node['schema']['x-example'] = ($param['example'] ?? '') ?: '{}'; break; case \Utopia\Storage\Validator\File::class: @@ -679,19 +713,15 @@ class OpenAPI3 extends Format } $enumKeys = []; - if (!empty($enum->map)) { - foreach ($enumValues as $enumValue) { - $enumKeys[] = $enum->map[$enumValue] ?? $enumValue; - } + foreach ($enumValues as $enumValue) { + $enumKeys[] = $enum->map[$enumValue] ?? $enumValue; } $node['schema']['items']['enum'] = $enumValues; if (!empty($enum->name)) { $node['schema']['items']['x-enum-name'] = $enum->name; } - if (!empty($enumKeys)) { - $node['schema']['items']['x-enum-keys'] = $enumKeys; - } + $node['schema']['items']['x-enum-keys'] = $enumKeys; } } if ($validator->getType() === 'integer') { @@ -720,19 +750,15 @@ class OpenAPI3 extends Format } $enumKeys = []; - if (!empty($enum->map)) { - foreach ($enumValues as $enumValue) { - $enumKeys[] = $enum->map[$enumValue] ?? $enumValue; - } + foreach ($enumValues as $enumValue) { + $enumKeys[] = $enum->map[$enumValue] ?? $enumValue; } $node['schema']['enum'] = $enumValues; if (!empty($enum->name)) { $node['schema']['x-enum-name'] = $enum->name; } - if (!empty($enumKeys)) { - $node['schema']['x-enum-keys'] = $enumKeys; - } + $node['schema']['x-enum-keys'] = $enumKeys; } } if ($validator->getType() === 'integer') { @@ -829,9 +855,7 @@ class OpenAPI3 extends Format /// If the enum flag is Set, add the enum values to the body $body['content'][$consumes[0]]['schema']['properties'][$name]['enum'] = $node['schema']['enum']; $body['content'][$consumes[0]]['schema']['properties'][$name]['x-enum-name'] = $node['schema']['x-enum-name'] ?? null; - if (isset($node['schema']['x-enum-keys'])) { - $body['content'][$consumes[0]]['schema']['properties'][$name]['x-enum-keys'] = $node['schema']['x-enum-keys']; - } + $body['content'][$consumes[0]]['schema']['properties'][$name]['x-enum-keys'] = $node['schema']['x-enum-keys']; } if ($node['schema']['x-upload-id'] ?? false) { @@ -930,7 +954,6 @@ class OpenAPI3 extends Format case 'json': $type = 'object'; - $output['components']['schemas'][$model->getType()]['properties'][$name]['additionalProperties'] = true; break; case 'array': @@ -996,6 +1019,20 @@ class OpenAPI3 extends Format } $readOnly = $rule['readOnly'] ?? false; + if ($rule['type'] == 'json') { + $output['components']['schemas'][$model->getType()]['properties'][$name] = [ + 'type' => $type, + 'additionalProperties' => true, + 'description' => $rule['description'] ?? '', + 'x-example' => $rule['example'] ?? null, + ]; + + if ($readOnly) { + $output['components']['schemas'][$model->getType()]['properties'][$name]['readOnly'] = true; + } + continue; + } + if ($rule['array']) { $output['components']['schemas'][$model->getType()]['properties'][$name] = [ 'type' => 'array', diff --git a/tests/unit/SDK/Specification/FormatTest.php b/tests/unit/SDK/Specification/FormatTest.php index 11f9c0d7f6..c70674cec6 100644 --- a/tests/unit/SDK/Specification/FormatTest.php +++ b/tests/unit/SDK/Specification/FormatTest.php @@ -2,6 +2,7 @@ namespace Tests\Unit\SDK\Specification; +use Appwrite\SDK\ContentType; use Appwrite\SDK\Method; use Appwrite\SDK\Response as SDKResponse; use Appwrite\SDK\Specification\Format; @@ -20,6 +21,7 @@ use Appwrite\Utopia\Response\Model\AlgoSha; use Appwrite\Utopia\Response\Model\AttributeLine; use Appwrite\Utopia\Response\Model\Error as ErrorModel; use Appwrite\Utopia\Response\Model\HealthStatus; +use Appwrite\Utopia\Response\Model\None as NoneModel; use Appwrite\Utopia\Response\Model\PlatformAndroid; use Appwrite\Utopia\Response\Model\PlatformApple; use Appwrite\Utopia\Response\Model\PlatformLinux; @@ -27,6 +29,7 @@ use Appwrite\Utopia\Response\Model\PlatformList; use Appwrite\Utopia\Response\Model\PlatformWeb; use Appwrite\Utopia\Response\Model\PlatformWindows; use Appwrite\Utopia\Response\Model\Preferences; +use Appwrite\Utopia\Response\Model\Provider; use Appwrite\Utopia\Response\Model\Team; use Appwrite\Utopia\Response\Model\User; use Appwrite\Utopia\Response\Model\Webhook; @@ -35,6 +38,7 @@ use Utopia\Database\Database; use Utopia\Database\Validator\Spatial; use Utopia\DI\Container; use Utopia\Http\Route; +use Utopia\Validator\JSON; use Utopia\Validator\Nullable; use Utopia\Validator\Text; @@ -383,4 +387,143 @@ final class FormatTest extends TestCase $this->assertArrayNotHasKey('format', $swaggerProperties['name']); $this->assertSame('password', $swagger['definitions']['webhook']['properties']['authPassword']['format']); } + + public function testNoContentMethodsKeepProducesMetadata(): void + { + Method::$processed = []; + Method::$errors = []; + + $route = (new Route('DELETE', '/v1/tests/:testId')) + ->desc('Delete test') + ->label('scope', 'tests.write') + ->label('sdk', new Method( + namespace: 'test', + group: null, + name: 'deleteTest', + description: 'Delete test.', + auth: [], + responses: [ + new SDKResponse( + code: 204, + model: Response::MODEL_NONE, + ), + ], + )) + ->param('testId', '', new Text(256), 'Test ID.'); + + $openApi = (new OpenAPI3(new Container(), [], [$route], [new NoneModel()], [], 0, 'console'))->parse(); + $swagger = (new Swagger2(new Container(), [], [$route], [new NoneModel()], [], 0, 'console'))->parse(); + + $openApiMethod = $openApi['paths']['/tests/{testId}']['delete']; + + $this->assertArrayNotHasKey('content', $openApiMethod['responses']['204']); + $this->assertSame(['application/json'], $openApiMethod['x-appwrite']['produces']); + $this->assertSame(['application/json'], $swagger['paths']['/tests/{testId}']['delete']['produces']); + } + + public function testBinaryResponsesEmitResponseContent(): void + { + Method::$processed = []; + Method::$errors = []; + + $route = (new Route('GET', '/v1/tests/icon')) + ->desc('Get test icon') + ->label('sdk', new Method( + namespace: 'test', + group: null, + name: 'getTestIcon', + description: 'Get test icon.', + auth: [], + responses: [ + new SDKResponse( + code: 200, + model: Response::MODEL_NONE, + ), + ], + contentType: ContentType::IMAGE_PNG, + )); + + $openApi = (new OpenAPI3(new Container(), [], [$route], [new NoneModel()], [], 0, 'console'))->parse(); + $swagger = (new Swagger2(new Container(), [], [$route], [new NoneModel()], [], 0, 'console'))->parse(); + + $openApiMethod = $openApi['paths']['/tests/icon']['get']; + + $this->assertSame( + ['type' => 'string', 'format' => 'binary'], + $openApiMethod['responses']['200']['content']['image/png']['schema'] + ); + $this->assertArrayNotHasKey('produces', $openApiMethod['x-appwrite']); + $this->assertSame(['image/png'], $swagger['paths']['/tests/icon']['get']['produces']); + } + + public function testAdditionalParametersAreIncludedInRequestBody(): void + { + Method::$processed = []; + Method::$errors = []; + + $route = (new Route('POST', '/v1/tests/graphql')) + ->desc('GraphQL test endpoint') + ->label('sdk', new Method( + namespace: 'test', + group: null, + name: 'queryTest', + description: 'GraphQL test endpoint.', + auth: [], + responses: [], + additionalParameters: [ + 'query' => [ + 'default' => [], + 'validator' => new JSON(), + 'description' => 'The query or queries to execute.', + 'optional' => false, + ], + ], + )); + + $openApi = (new OpenAPI3(new Container(), [], [$route], [], [], 0, 'console'))->parse(); + $swagger = (new Swagger2(new Container(), [], [$route], [], [], 0, 'console'))->parse(); + + $openApiQuery = $openApi['paths']['/tests/graphql']['post']['requestBody']['content']['application/json']['schema']['properties']['query']; + $swaggerQuery = $swagger['paths']['/tests/graphql']['post']['parameters'][0]['schema']['properties']['query']; + + $this->assertSame('object', $openApiQuery['type']); + $this->assertEquals($swaggerQuery, $openApiQuery); + } + + public function testJsonModelRulesKeepAdditionalPropertiesAndSkipNullable(): void + { + Method::$processed = []; + Method::$errors = []; + + $route = (new Route('GET', '/v1/tests/provider')) + ->desc('Get test provider') + ->label('sdk', new Method( + namespace: 'test', + group: null, + name: 'getTestProvider', + description: 'Get test provider.', + auth: [], + responses: [ + new SDKResponse( + code: 200, + model: Response::MODEL_PROVIDER, + ), + ], + )); + + $models = [ + new Provider(), + new ErrorModel(), + ]; + + $openApi = (new OpenAPI3(new Container(), [], [$route], $models, [], 0, 'console'))->parse(); + $swagger = (new Swagger2(new Container(), [], [$route], $models, [], 0, 'console'))->parse(); + + $openApiOptions = $openApi['components']['schemas']['provider']['properties']['options']; + $swaggerOptions = $swagger['definitions']['provider']['properties']['options']; + + $this->assertTrue($openApiOptions['additionalProperties']); + $this->assertArrayNotHasKey('nullable', $openApiOptions); + $this->assertEquals($swaggerOptions, $openApiOptions); + } }