mirror of
https://github.com/appwrite/appwrite.git
synced 2026-11-18 20:36:03 +00:00
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:
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',
|
||||
|
||||
@@ -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);
|
||||
}
|
||||
}
|
||||
Reference in new issue
Block a user