Merge pull request #12357 from appwrite/fix/spec-regional-endpoint-validation

Fix generated spec endpoint and enum defaults

src/Appwrite/Platform/Modules/Avatars/Http/Screenshots/Get.php

@@ -72,7 +72,7 @@ class Get extends Action
             ->param('userAgent', '', new Text(512), 'Custom user agent string. Defaults to browser default.', true, example: 'Mozilla/5.0 (iPhone; CPU iPhone OS 14_0 like Mac OS X) AppleWebKit/605.1.15')
             ->param('fullpage', false, new Boolean(true), 'Capture full page scroll. Pass 0 for viewport only, or 1 for full page. Defaults to 0.', true, example: 'true')
             ->param('locale', '', new Text(10), 'Browser locale (e.g., "en-US", "fr-FR"). Defaults to browser default.', true, example: 'en-US')
-            ->param('timezone', '', new WhiteList(timezone_identifiers_list()), 'IANA timezone identifier (e.g., "America/New_York", "Europe/London"). Defaults to browser default.', true, example: 'america/new_york')
+            ->param('timezone', '', new WhiteList(timezone_identifiers_list()), 'IANA timezone identifier (e.g., "America/New_York", "Europe/London"). Defaults to browser default.', true, example: 'America/New_York')
             ->param('latitude', 0, new Range(-90, 90, Range::TYPE_FLOAT), 'Geolocation latitude. Pass a number between -90 to 90. Defaults to 0.', true, example: '37.7749')
             ->param('longitude', 0, new Range(-180, 180, Range::TYPE_FLOAT), 'Geolocation longitude. Pass a number between -180 to 180. Defaults to 0.', true, example: '-122.4194')
             ->param('accuracy', 0, new Range(0, 100000, Range::TYPE_FLOAT), 'Geolocation accuracy in meters. Pass a number between 0 to 100000. Defaults to 0.', true, example: '100')

src/Appwrite/SDK/Specification/Format.php

@@ -29,6 +29,7 @@ abstract class Format
         'name' => '',
         'description' => '',
         'endpoint' => 'https://localhost',
+        'endpoint.docs' => 'https://<REGION>.cloud.appwrite.io/v1',
         'version' => '1.0.0',
         'terms' => '',
         'support.email' => '',
@@ -1032,6 +1033,19 @@ abstract class Format
         return $values;
     }
 
+    protected function shouldEmitDefaultForSchema(mixed $default, array $schema): bool
+    {
+        if (isset($schema['enum'])) {
+            return \in_array($default, $schema['enum'], true);
+        }
+
+        if (isset($schema['items']['enum'])) {
+            return \is_array($default) && empty(\array_diff($default, $schema['items']['enum']));
+        }
+
+        return true;
+    }
+
     protected function getRequestParameterConfig(string $service, string $method, string $param, bool $optional, bool $nullable, mixed $default): array
     {
         $config = [

src/Appwrite/SDK/Specification/Format/OpenAPI3.php

@@ -55,11 +55,22 @@ class OpenAPI3 extends Format
             'servers' => [
                 [
                     'url' => $this->getParam('endpoint', ''),
+                    'description' => 'Appwrite Cloud endpoint.',
                 ],
                 [
-                    'url' => $this->getParam('endpoint.docs', ''),
+                    'url' => \str_replace('<REGION>', '{region}', $this->getParam('endpoint.docs', '')),
+                    'description' => 'Appwrite Cloud regional endpoint. Replace `{region}` with your project region.',
+                    'variables' => [
+                        'region' => [
+                            'default' => 'fra',
+                            'description' => 'Appwrite Cloud region.',
+                        ],
+                    ],
                 ],
             ],
+            'x-appwrite' => [
+                'endpointDocs' => $this->getParam('endpoint.docs', ''),
+            ],
             'paths' => [],
             'tags' => $this->services,
             'components' => [
@@ -768,7 +779,7 @@ class OpenAPI3 extends Format
                         break;
                 }
 
-                if ($parameter['emitDefault']) { // Param has default value
+                if ($parameter['emitDefault'] && $this->shouldEmitDefaultForSchema($param['default'], $node['schema'])) { // Param has default value
                     $node['schema']['default'] = $param['default'];
                 }
 

src/Appwrite/SDK/Specification/Format/Swagger2.php

@@ -55,6 +55,9 @@ class Swagger2 extends Format
             ],
             'host' => \parse_url($this->getParam('endpoint', ''), PHP_URL_HOST),
             'x-host-docs' => \parse_url($this->getParam('endpoint.docs', ''), PHP_URL_HOST),
+            'x-appwrite' => [
+                'endpointDocs' => $this->getParam('endpoint.docs', ''),
+            ],
             'basePath' => \parse_url($this->getParam('endpoint', ''), PHP_URL_PATH),
             'schemes' => [\parse_url($this->getParam('endpoint', ''), PHP_URL_SCHEME)],
             'consumes' => ['application/json', 'multipart/form-data'],
@@ -731,7 +734,7 @@ class Swagger2 extends Format
                         break;
                 }
 
-                if ($parameter['emitDefault']) { // Param has default value
+                if ($parameter['emitDefault'] && $this->shouldEmitDefaultForSchema($param['default'], $node)) { // Param has default value
                     $node['default'] = $param['default'];
                 }
 
@@ -767,10 +770,13 @@ class Swagger2 extends Format
                     $body['schema']['properties'][$name] = [
                         'type' => $node['type'],
                         'description' => $node['description'],
-                        'default' => $node['default'] ?? null,
                         'x-example' => $node['x-example'] ?? null,
                     ];
 
+                    if (\array_key_exists('default', $node)) {
+                        $body['schema']['properties'][$name]['default'] = $node['default'];
+                    }
+
                     if (isset($node['format'])) {
                         $body['schema']['properties'][$name]['format'] = $node['format'];
                     }