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.
This commit is contained in:
Chirag Aggarwal authored and GitHub committed 2026-06-11 10:46:24 +05:30
1 parent b428d6e41c
commit 5453271705
2 files changed
+201 -21

No files matched your search

@@ -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',
+143
View File
@@ -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);
}
}