fix: omit unset optional string examples across SDK languages

src/SDK/Language.php

@@ -458,6 +458,17 @@ protected function getArraySchemaModel(Schema|Parameter $value): ?string
         return $items instanceof ReferenceSchema ? $this->normalizeSchemaReference($items->reference) : null;
     }
 
+    /** Whether an optional string example should leave the field unset. */
+    public function shouldOmitExample(Schema|Parameter $value, ?bool $required = null): bool
+    {
+        $required ??= $value instanceof Parameter ? $value->required : true;
+
+        return !$required
+            && $this->getSchemaType($value) === self::TYPE_STRING
+            && !$this->isStringEnum($value)
+            && \in_array($this->getSchemaExample($value), [null, ''], true);
+    }
+
     protected function getSchemaExample(Schema|Parameter $value): mixed
     {
         $schema = $this->getSchema($value);

src/SDK/Language/Dart.php

@@ -194,7 +194,7 @@ public function getParamExample(Schema|Parameter $param, string $lang = ''): str
         $type       = $this->getSchemaType($param);
         $example    = $this->getSchemaExample($param);
 
-        $hasExample = !empty($example) || $example === 0 || $example === false;
+        $hasExample = $example !== null && $example !== '';
 
         if (!$hasExample) {
             return match ($type) {
@@ -203,7 +203,7 @@ public function getParamExample(Schema|Parameter $param, string $lang = ''): str
                 self::TYPE_BOOLEAN => 'false',
                 self::TYPE_FILE => 'InputFile(path: \'./path-to-files/image.jpg\', filename: \'image.jpg\')',
                 self::TYPE_INTEGER, self::TYPE_NUMBER => '0',
-                self::TYPE_STRING => "''",
+                self::TYPE_STRING => $this->shouldOmitExample($param) ? 'null' : "''",
             };
         }
 

src/SDK/Language/DotNet.php

@@ -225,7 +225,7 @@ public function getParamExample(Schema|Parameter $param, string $lang = ''): str
 
         $output = '';
 
-        if (empty($example) && $example !== 0 && $example !== false) {
+        if ($example === null || $example === '') {
             switch ($type) {
                 case self::TYPE_FILE:
                     $output .= 'InputFile.FromPath("./path-to-files/image.jpg")';
@@ -238,7 +238,7 @@ public function getParamExample(Schema|Parameter $param, string $lang = ''): str
                     $output .= 'false';
                     break;
                 case self::TYPE_STRING:
-                    $output .= '""';
+                    $output .= $this->shouldOmitExample($param) ? 'null' : '""';
                     break;
                 case self::TYPE_OBJECT:
                     $output .= '[object]';

src/SDK/Language/Go.php

@@ -255,7 +255,7 @@ public function getParamExample(Schema|Parameter $param, string $lang = ''): str
 
         $output = '';
 
-        if (empty($example) && $example !== 0 && $example !== false) {
+        if ($example === null || $example === '') {
             switch ($type) {
                 case self::TYPE_NUMBER:
                 case self::TYPE_INTEGER:

src/SDK/Language/GraphQL.php

@@ -50,7 +50,7 @@ public function getParamExample(Schema|Parameter $param, string $lang = ''): str
         $type       = $this->getSchemaType($param);
         $example    = $this->getSchemaExample($param);
 
-        $hasExample = !empty($example) || $example === 0 || $example === false;
+        $hasExample = $example !== null && $example !== '';
 
         if (!$hasExample) {
             return match ($type) {

src/SDK/Language/Kotlin.php

@@ -185,7 +185,7 @@ public function getParamExample(Schema|Parameter $param, string $lang = 'kotlin'
 
         $output = '';
 
-        if (empty($example) && $example !== 0 && $example !== false) {
+        if ($example === null || $example === '') {
             switch ($type) {
                 case self::TYPE_FILE:
                     $output .= 'InputFile.fromPath("file.png")';
@@ -198,7 +198,7 @@ public function getParamExample(Schema|Parameter $param, string $lang = 'kotlin'
                     $output .= 'false';
                     break;
                 case self::TYPE_STRING:
-                    $output .= "\"\"";
+                    $output .= $this->shouldOmitExample($param) ? 'null' : "\"\"";
                     break;
                 case self::TYPE_OBJECT:
                     $output .= $lang === 'java'

src/SDK/Language/PHP.php

@@ -390,15 +390,15 @@ public function getParamExample(Schema|Parameter $param, string $lang = ''): str
 
         $output = '';
 
-        if (empty($example) && $example !== 0 && $example !== false) {
+        if ($example === null || $example === '') {
             switch ($type) {
                 case self::TYPE_NUMBER:
                 case self::TYPE_INTEGER:
                 case self::TYPE_BOOLEAN:
                     $output .= 'null';
                     break;
                 case self::TYPE_STRING:
-                    $output .= "''";
+                    $output .= $this->shouldOmitExample($param) ? 'null' : "''";
                     break;
                 case self::TYPE_ARRAY:
                 case self::TYPE_OBJECT:

src/SDK/Language/Python.php

@@ -399,15 +399,15 @@ public function getParamExample(Schema|Parameter $param, string $lang = ''): str
         $type = $this->getSchemaType($param);
         $example = $this->getSchemaExample($param);
 
-        $hasExample = !empty($example) || $example === 0 || $example === false;
+        $hasExample = $example !== null && $example !== '';
 
         if (!$hasExample) {
             return match ($type) {
                 self::TYPE_ARRAY => '[]',
                 self::TYPE_FILE => 'InputFile.from_path(\'file.png\')',
                 self::TYPE_INTEGER, self::TYPE_NUMBER , self::TYPE_BOOLEAN => 'None',
                 self::TYPE_OBJECT => '{}',
-                self::TYPE_STRING => "''",
+                self::TYPE_STRING => $this->shouldOmitExample($param) ? 'None' : "''",
             };
         }
 
@@ -546,7 +546,11 @@ protected function getRequestModelInstanceExample(string $modelName, Specificati
         }
 
         $arguments = [];
-        foreach ($model->properties as $property) {
+        foreach ($model->properties as $name => $property) {
+            if ($this->shouldOmitExample($property, \in_array($name, $model->required, true))) {
+                continue;
+            }
+
             $arguments[] = $this->getModelFieldName($property, $model->properties)
                 . ' = ' . $this->getRequestModelPropertyExample($property, $spec, $serviceName);
         }

src/SDK/Language/REST.php

@@ -32,7 +32,7 @@ public function getParamExample(Schema|Parameter $param, string $lang = ''): str
         $type       = $this->getSchemaType($param);
         $example    = $this->getSchemaExample($param);
 
-        $hasExample = !empty($example) || $example === 0 || $example === false;
+        $hasExample = $example !== null && $example !== '';
 
         if (!$hasExample) {
             return match ($type) {

src/SDK/Language/Ruby.php

@@ -255,15 +255,15 @@ public function getParamExample(Schema|Parameter $param, string $lang = ''): str
 
         $output = '';
 
-        if (empty($example) && $example !== 0 && $example !== false) {
+        if ($example === null || $example === '') {
             switch ($type) {
                 case self::TYPE_NUMBER:
                 case self::TYPE_INTEGER:
                 case self::TYPE_BOOLEAN:
                     $output .= 'nil';
                     break;
                 case self::TYPE_STRING:
-                    $output .= "''";
+                    $output .= $this->shouldOmitExample($param) ? 'nil' : "''";
                     break;
                 case self::TYPE_ARRAY:
                     $output .= '[]';

src/SDK/Language/Rust.php

@@ -333,7 +333,7 @@ public function getParamExample(Schema|Parameter $param, string $lang = ''): str
 
         $output = "";
 
-        if (empty($example) && $example !== 0 && $example !== false) {
+        if ($example === null || $example === '') {
             switch ($type) {
                 case self::TYPE_NUMBER:
                 case self::TYPE_INTEGER:
@@ -540,6 +540,10 @@ function ($value, $indent = 0): string {
             new TwigFilter("returnType", fn(Operation $method, Specification $spec, string $namespace, string $generic = "serde_json::Value"): string => $this->getReturnType($method, $spec)),
             new TwigFilter("caseEnumKey", fn(string $value): string => $this->toPascalCase($value)),
             new TwigFilter("docsArgumentExample", function (Schema|Parameter $param, string $crateName): string {
+                if ($this->shouldOmitExample($param)) {
+                    return 'None';
+                }
+
                 if ($this->getSchemaType($param) === self::TYPE_FILE) {
                     $value = $this->toCaseSnake($param instanceof Parameter ? $param->name : 'file');
                     if (isset($this->getIdentifierOverrides()[$value])) {

src/SDK/Language/Swift.php

@@ -375,7 +375,7 @@ public function getParamExample(Schema|Parameter $param, string $lang = ''): str
 
         $output = '';
 
-        if (empty($example) && $example !== 0 && $example !== false) {
+        if ($example === null || $example === '') {
             switch ($type) {
                 case self::TYPE_FILE:
                     $output .= 'InputFile.fromPath("file.png")';
@@ -388,7 +388,7 @@ public function getParamExample(Schema|Parameter $param, string $lang = ''): str
                     $output .= 'false';
                     break;
                 case self::TYPE_STRING:
-                    $output .= '""';
+                    $output .= $this->shouldOmitExample($param) ? 'nil' : '""';
                     break;
                 case self::TYPE_ARRAY:
                     $output .= '[]';

src/SDK/Language/Web.php

@@ -327,15 +327,15 @@ public function getParamExample(Schema|Parameter $param, string $lang = ''): str
         $type       = $this->getSchemaType($param);
         $example    = $this->getSchemaExample($param);
 
-        $hasExample = !empty($example) || $example === 0 || $example === false;
+        $hasExample = $example !== null && $example !== '';
 
         if (!$hasExample) {
             return match ($type) {
                 self::TYPE_ARRAY => '[]',
                 self::TYPE_FILE => $this->getFileExample(),
                 self::TYPE_INTEGER, self::TYPE_NUMBER, self::TYPE_BOOLEAN => $this->getScalarExampleFallback($param),
                 self::TYPE_OBJECT => '{}',
-                self::TYPE_STRING => "''",
+                self::TYPE_STRING => $this->shouldOmitExample($param) ? 'undefined' : "''",
             };
         }
 

src/SDK/SDK.php

@@ -150,6 +150,7 @@ public function __construct(protected Language $language, protected Specificatio
         $this->twig->addFilter(new TwigFilter('caseJson', fn($value) => (is_array($value)) ? json_encode($value) : $value, ['is_safe' => ['html']]));
         $this->twig->addFilter(new TwigFilter('typeName', fn(Schema|Parameter $value, ?Specification $spec = null): string => $this->language->getTypeName($value, $spec ?? $this->spec), ['is_safe' => ['html']]));
         $this->twig->addFilter(new TwigFilter('getValidResponseModels', fn(Operation $value): array => $this->getValidResponseModels($value)));
+        $this->twig->addFilter(new TwigFilter('omitExample', fn(Schema|Parameter $value): bool => $this->language->shouldOmitExample($value)));
         $this->twig->addFilter(new TwigFilter('paramExample', fn(Schema|Parameter $value): string => $this->language->isOpenStringEnum($value)
             ? $this->language->getSuggestedEnumExample($value)
             : $this->language->getParamExample($value), ['is_safe' => ['html']]));

templates/go/docs/example.md.twig

@@ -1,5 +1,6 @@
+{% set exampleParameters = (method | parameters('all')) | filter(parameter => not (parameter | omitExample)) %}
 ```go
-{% set requireFilesPkg = (method | parameters('all')) | filter(parameter => (parameter | schemaType) == 'file') | length > 0 -%}
+{% set requireFilesPkg = exampleParameters | filter(parameter => (parameter | schemaType) == 'file') | length > 0 -%}
 {%- set packagePath = sdk | goPackagePath -%}
 {%- set imports = [packagePath ~ '/appwrite', packagePath ~ '/' ~ (service.name | caseLower)] -%}
 {%- if requireFilesPkg -%}
@@ -29,11 +30,11 @@ func main() {
 
 	service := {{ service.name | caseLower }}.New(client)
 
-{% if (method | parameters('all')) | length == 0 %}
+{% if exampleParameters | length == 0 %}
 	response, err := service.{{ (method | methodName) | caseUcfirst }}()
 {% else %}
 	response, err := service.{{ (method | methodName) | caseUcfirst }}(
-{% for parameter in (method | parameters('all')) %}
+{% for parameter in exampleParameters %}
 {% if parameter.required %}
 		{{ parameter | paramExample }},
 {% else %}

templates/graphql/docs/example.md.twig

@@ -1,3 +1,4 @@
+{% set exampleParameters = (method | parameters('all')) | filter(parameter => not (parameter | omitExample)) %}
 ```graphql
 {% macro getProperty(definitions, responseModel, depth) %}
         {%~ for definitionName, definition in definitions %}
@@ -36,16 +37,16 @@ Content-Length: *Length of your entity body in bytes*
 --{{boundary}}
 Content-Disposition: form-data; name="operations"
 
-{ "query": "mutation { {{ service.name | caseCamel }}{{ (method | methodName) | caseCamel | caseUcfirst }}({% for parameter in (method | parameters('all'))  %}{{ parameter.name | caseCamel }}: ${{ parameter.name | caseCamel }}{% if not loop.last %}, {% endif %}{% endfor %}) { id }" }, "variables": { {% for parameter in (method | parameters('all'))  %}"{{ parameter.name | caseCamel }}": {{ parameter | paramExample }}{% if not loop.last %}, {% endif %}{% endfor %} } }
+{ "query": "mutation { {{ service.name | caseCamel }}{{ (method | methodName) | caseCamel | caseUcfirst }}({% for parameter in exampleParameters  %}{{ parameter.name | caseCamel }}: ${{ parameter.name | caseCamel }}{% if not loop.last %}, {% endif %}{% endfor %}) { id }" }, "variables": { {% for parameter in exampleParameters  %}"{{ parameter.name | caseCamel }}": {{ parameter | paramExample }}{% if not loop.last %}, {% endif %}{% endfor %} } }
 
 --{{boundary}}
 Content-Disposition: form-data; name="map"
 
 {% set counter = 0 %}
-{ {% for parameter in (method | parameters('all'))  %}{% if (parameter | schemaType) == 'file' %}"{{ counter }}": ["variables.{{ parameter.name | caseCamel }}"]{% if not loop.last %}, {% endif %}{% set counter = counter + 1 %}{% endif %}{% endfor %} }
+{ {% for parameter in exampleParameters  %}{% if (parameter | schemaType) == 'file' %}"{{ counter }}": ["variables.{{ parameter.name | caseCamel }}"]{% if not loop.last %}, {% endif %}{% set counter = counter + 1 %}{% endif %}{% endfor %} }
 
 {% set counter = 0 %}
-{% for parameter in (method | parameters('all'))  %}
+{% for parameter in exampleParameters  %}
 {% if (parameter | schemaType) == 'file' %}
 --{{ boundary }}
 Content-Disposition: form-data; name="{{ counter }}"; filename="{{ parameter.name }}.ext"
@@ -62,8 +63,8 @@ query {
 {%~ else %}
 mutation {
 {%~ endif %}
-    {{ service.name | caseCamel }}{{ (method | methodName) | caseCamel | caseUcfirst }}{% if (method | parameters('all'))  | length == 0 %} {{ '{' }}{% else %}(
-        {%~ for parameter in (method | parameters('all'))  %}
+    {{ service.name | caseCamel }}{{ (method | methodName) | caseCamel | caseUcfirst }}{% if exampleParameters  | length == 0 %} {{ '{' }}{% else %}(
+        {%~ for parameter in exampleParameters  %}
         {{ parameter.name | caseCamel }}: {{ parameter | paramExample }}{% if not loop.last %},{% endif %}
 
         {%~ endfor %}

templates/rest/docs/example.md.twig

@@ -16,7 +16,7 @@ Host: {{ ((spec | endpoint) | split('/'))[2] }}
 
 {% if (method | parameters('body')) %}
 {
-{% for parameter in (method | parameters('body')) %}
+{% for parameter in ((method | parameters('body')) | filter(parameter => not (parameter | omitExample))) %}
   "{{ parameter.name }}": {{ parameter | paramExample }}{% if not loop.last %},{% endif ~%}
 {% endfor %}
 }
@@ -25,7 +25,7 @@ Host: {{ ((spec | endpoint) | split('/'))[2] }}
 {% if (key | caseLower) == 'content-type' and header == 'multipart/form-data' %}
 Content-Length: *Length of your entity body in bytes*
 
-{% for parameter in (method | parameters('body')) %}
+{% for parameter in ((method | parameters('body')) | filter(parameter => not (parameter | omitExample))) %}
 --{{boundary}}
 Content-Disposition: form-data; name="{{parameter.name}}{% if (parameter | schemaType) == "array" %}[]{% endif %}"