add deprecation handling in templates

example.php

@@ -42,7 +42,7 @@ function getSSLPage($url) {
      $platform = 'console';
     // $platform = 'server';
 
-    $spec = getSSLPage("https://raw.githubusercontent.com/appwrite/appwrite/1.7.x/app/config/specs/swagger2-latest-{$platform}.json");
+    $spec = getSSLPage("https://raw.githubusercontent.com/appwrite/appwrite/deprecate-old-methods/app/config/specs/swagger2-1.8.x-{$platform}.json");
 
     if(empty($spec)) {
         throw new Exception('Failed to fetch spec from Appwrite server');

src/SDK/SDK.php

@@ -207,6 +207,22 @@ public function __construct(Language $language, Spec $spec)
             }
             return $value;
         }));
+        $this->twig->addFilter(new TwigFilter('capitalizeFirst', function ($value) {
+            return ucfirst($value);
+        }));
+        $this->twig->addFilter(new TwigFilter('caseSnakeExceptFirstDot', function ($value) {
+            $parts = explode('.', $value, 2);
+            $toSnake = function ($str) {
+                preg_match_all('!([A-Za-z][A-Z0-9]*(?=$|[A-Z][a-z0-9])|[A-Za-z][a-z0-9]+)!', $str, $matches);
+                return implode('_', array_map(function ($m) {
+                    return $m === strtoupper($m) ? strtolower($m) : lcfirst($m);
+                }, $matches[0]));
+            };
+            if (count($parts) < 2) {
+                return $toSnake($value);
+            }
+            return $parts[0] . '.' . $toSnake($parts[1]);
+        }));
     }
 
     /**

src/Spec/Swagger2.php

@@ -176,6 +176,7 @@ protected function parseMethod(string $methodName, string $pathName, array $meth
             'consumes' => $method['consumes'] ?? [],
             'cookies' => $method['x-appwrite']['cookies'] ?? false,
             'type' => $method['x-appwrite']['type'] ?? false,
+            'deprecated' => $method['deprecated'] ?? false,
             'headers' => [],
             'parameters' => [
                 'all' => [],
@@ -188,6 +189,11 @@ protected function parseMethod(string $methodName, string $pathName, array $meth
             'responseModel' => $responseModel,
         ];
 
+        if ($method['x-appwrite']['deprecated'] ?? false) {
+            $output['since'] = $method['x-appwrite']['deprecated']['since'] ?? '';
+            $output['replaceWith'] = $method['x-appwrite']['deprecated']['replaceWith'] ?? '';
+        }
+
         if ($output['type'] == 'graphql') {
             $output['headers']['x-sdk-graphql'] = "true";
         }

templates/android/library/src/main/java/io/package/services/Service.kt.twig

@@ -38,6 +38,19 @@ class {{ service.name | caseUcfirst }}(client: Client) : Service(client) {
      * @return [{{ method | returnType(spec, sdk.namespace | caseDot) | raw }}]
     {%~ endif %}
      */
+    {%~ if method.deprecated %}
+    {%~ if method.since and method.replaceWith %}
+    @Deprecated(
+        message = "This API is deprecated since {{ method.since }} and uses outdated terminologies. Please use `{{ method.replaceWith | capitalizeFirst }}` instead.",
+        replaceWith = ReplaceWith("{{ sdk.namespace | caseDot }}.services.{{ method.replaceWith | capitalizeFirst }}"),
+        since = "{{ method.since }}"
+    )
+    {%~ else %}
+    @Deprecated(
+        message = "This API is deprecated."
+    )
+    {%~ endif %}
+    {%~ endif %}
     {%~ if method.parameters.all | reduce((carry, param) => carry or not param.required) %}
     @JvmOverloads
     {%~ endif %}
@@ -192,6 +205,19 @@ class {{ service.name | caseUcfirst }}(client: Client) : Service(client) {
      * @return [{{ method | returnType(spec, sdk.namespace | caseDot) | raw }}]
     {%~ endif %}
      */
+    {%~ if method.deprecated %}
+    {%~ if method.since and method.replaceWith %}
+    @Deprecated(
+        message = "This API is deprecated since {{ method.since }} and uses outdated terminologies. Please use `{{ method.replaceWith | capitalizeFirst }}` instead.",
+        replaceWith = ReplaceWith("{{ sdk.namespace | caseDot }}.services.{{ method.replaceWith | capitalizeFirst }}"),
+        since = "{{ method.since }}"
+    )
+    {%~ else %}
+    @Deprecated(
+        message = "This API is deprecated."
+    )
+    {%~ endif %}
+    {%~ endif %}
     {%~ if method.parameters.all | reduce((carry, param) => carry or not param.required) %}
     @JvmOverloads
     {%~ endif %}

templates/apple/Sources/Services/Service.swift.twig

@@ -23,6 +23,13 @@ open class {{ service.name | caseUcfirst | overrideIdentifier }}: Service {
     {%~ if method.type == "webAuth" %}
     @available(iOS 14.0, macOS 11.0, tvOS 14.0, watchOS 7.0, *)
     {%~ endif %}
+    {%~ if method.deprecated %}
+    {%~ if method.since and method.replaceWith %}
+    @available(*, deprecated, message: "This API is deprecated since {{ method.since }} and uses outdated terminologies. Please use `{{ method.replaceWith | capitalizeFirst }}` instead.")
+    {%~ else %}
+    @available(*, deprecated, message: "This API is deprecated.")
+    {%~ endif %}
+    {%~ endif %}
     open func {{ method.name | caseCamel | overrideIdentifier }}{% if method.responseModel | hasGenericType(spec) %}<T>{% endif %}(
         {%~ for parameter in method.parameters.all %}
         {{ parameter.name | caseCamel | escapeSwiftKeyword }}: {{ parameter | typeName(spec) | raw }}{% if not parameter.required or parameter.nullable %}? = nil{% endif %}{% if not loop.last or 'multipart/form-data' in method.consumes or method.responseModel | hasGenericType(spec) %},{% endif %}
@@ -87,6 +94,13 @@ open class {{ service.name | caseUcfirst | overrideIdentifier }}: Service {
     {%~ if method.type == "webAuth" %}
     @available(iOS 14.0, macOS 11.0, tvOS 14.0, watchOS 7.0, *)
     {%~ endif %}
+    {%~ if method.deprecated %}
+    {%~ if method.since and method.replaceWith %}
+    @available(*, deprecated, message: "This API is deprecated since {{ method.since }} and uses outdated terminologies. Please use `{{ method.replaceWith | capitalizeFirst }}` instead.")
+    {%~ else %}
+    @available(*, deprecated, message: "This API is deprecated.")
+    {%~ endif %}
+    {%~ endif %}
     open func {{ method.name | caseCamel }}(
         {%~ for parameter in method.parameters.all %}
         {{ parameter.name | caseCamel | escapeSwiftKeyword }}: {{ parameter | typeName(spec) | raw }}{% if not parameter.required or parameter.nullable %}? = nil{% endif %}{% if not loop.last or 'multipart/form-data' in method.consumes %},{% endif %}

templates/cli/lib/commands/command.js.twig

@@ -59,7 +59,7 @@ const {{ service.name | caseLower }} = new Command("{{ service.name | caseLower
 /**
  * @param {{ "{" }}{{ service.name | caseUcfirst }}{{ method.name | caseUcfirst }}RequestParams{{ "}" }} params
  */
-{%~ block decleration -%}
+{% block decleration %}
 const {{ service.name | caseLower }}{{ method.name | caseUcfirst }} = async ({
         {%- for parameter in method.parameters.all -%}
             {{ parameter.name | caseCamel | escapeKeyword }},
@@ -72,7 +72,13 @@ const {{ service.name | caseLower }}{{ method.name | caseUcfirst }} = async ({
         {%- if method.type == 'location' -%}, destination{%- endif -%}
         {% if hasConsolePreview(method.name,service.name) %}, console{%- endif -%}
 }) => {
-{%~ endblock %}
+{% if method.deprecated %}
+{% if method.since and method.replaceWith %}
+    console.warn('Warning: This command is deprecated since {{ method.since }}.{% if method.replaceWith %} Please use "{{ method.replaceWith | replace({'.': ' '}) }}" instead.{% endif %}');
+{% else %}
+    console.warn('Warning: This command is deprecated.');
+{% endif %}
+{% endif %}
     let client = !sdk ? await {% if service.name == "projects" %}sdkForConsole(){% else %}sdkForProject(){% endif %} :
     sdk;
     let apiPath = '{{ method.path }}'{% for parameter in method.parameters.path %}.replace('{{ '{' }}{{ parameter.name | caseCamel }}{{ '}' }}', {{ parameter.name | caseCamel | escapeKeyword }}){% endfor %};
@@ -82,13 +88,14 @@ const {{ service.name | caseLower }}{{ method.name | caseUcfirst }} = async ({
 {{ include('cli/base/requests/api.twig') }}
 {% endif %}
 }
+{% endblock %}
 
 {% endfor %}
 {% for method in service.methods %}
 {{service.name | caseLower }}
     .command(`{{ method.name | caseKebab }}`)
 {% autoescape false %}
-    .description(`{{ method.description | replace({'`':'\''}) | replace({'\n':' '}) | replace({'\n \n':' '}) }}`)
+    .description(`{% if method.deprecated %}[DEPRECATED] This command is deprecated.{% if method.replaceWith %} Please use '{{ method.replaceWith | replace({'.': ' '}) }}' instead.{% endif %} {% endif %}{{ method.description | replace({'`':'\''}) | replace({'\n':' '}) | replace({'\n \n':' '}) }}`)
 {% for parameter in method.parameters.all %}
     .{% if parameter.required and not parameter.nullable %}requiredOption{% else %}option{% endif %}(`--{{ parameter.name | escapeKeyword | caseKebab }}{% if parameter | typeName == 'boolean' %} [value]{% else %} {% if parameter.array.type|length > 0 %}[{% else %}<{% endif %}{{ parameter.name | escapeKeyword | caseKebab }}{% if parameter.array.type|length > 0 %}...{% endif %}{% if parameter.array.type|length > 0 %}]{% else %}>{% endif %}{% endif %}`, `{{ parameter.description | replace({'`':'\''}) | replace({'\n':' '}) | replace({'\n \n':' '}) }}`{% if parameter | typeName == 'boolean' %}, (value) => value === undefined ? true : parseBool(value){% elseif parameter | typeName == 'number' %}, parseInteger{% endif %})
 {% endfor %}

templates/dart/lib/services/service.dart.twig

@@ -17,6 +17,13 @@ class {{ service.name | caseUcfirst }} extends Service {
 {%~ if method.description %}
 {{ method.description | dartComment }}
 {% endif %}
+{%~ if method.deprecated %}
+{%~ if method.since and method.replaceWith %}
+    @Deprecated('This API is deprecated since {{ method.since }} and uses outdated terminologies. Please use `{{ method.replaceWith | capitalizeFirst }}` instead.')
+{%~ else %}
+    @Deprecated('This API is deprecated.')
+{%~ endif %}
+{%~ endif %}
     {% if method.type == 'location' %}Future<Uint8List>{% else %}{% if method.responseModel and method.responseModel != 'any' %}Future<models.{{method.responseModel | caseUcfirst | overrideIdentifier}}>{% else %}Future{% endif %}{% endif %} {{ method.name | caseCamel | overrideIdentifier }}({{ _self.method_parameters(method.parameters.all, method.consumes) }}) async {
         final String apiPath = '{{ method.path }}'{% for parameter in method.parameters.path %}.replaceAll('{{ '{' }}{{ parameter.name | caseCamel }}{{ '}' }}', {{ parameter.name | caseCamel | overrideIdentifier }}{% if parameter.enumValues | length > 0  %}.value{% endif %}){% endfor %};
 

templates/deno/src/services/service.ts.twig

@@ -77,6 +77,13 @@ export class {{ service.name | caseUcfirst }} extends Service {
 {% endfor %}
      * @throws {AppwriteException}
      * @returns {Promise}
+     {%~ if method.deprecated %}
+     {%~ if method.since and method.replaceWith %}
+     * @deprecated This API is deprecated since {{ method.since }} and uses outdated terminologies.{% if method.replaceWith %} Please use `{{ method.replaceWith | capitalizeFirst }}` instead.{% endif %} 
+     {%~ else %}
+     * @deprecated This API is deprecated.
+     {%~ endif %}
+    {%~ endif %}
      */
     async {{ method.name | caseCamel }}{% if generics %}<{{generics}}>{% endif %}({% for parameter in method.parameters.all %}{{ parameter.name | caseCamel | escapeKeyword }}{% if not parameter.required or parameter.nullable %}?{% endif %}: {{ parameter | typeName }}{% if not loop.last %}, {% endif %}{% endfor %}{% if 'multipart/form-data' in method.consumes %}, onProgress = (progress: UploadProgress) => {}{% endif %}): Promise<{% if method.type == 'webAuth' %}string{% elseif method.type == 'location' %}ArrayBuffer{% else %}{% if method.responseModel and method.responseModel != 'any' %}{% if not spec.definitions[method.responseModel].additionalProperties %}Models.{% endif %}{{method.responseModel | caseUcfirst}}{% if generics_return %}<{{generics_return}}>{% endif %}{% else %}Response{% endif %}{% endif %}> {
 {% for parameter in method.parameters.all %}

templates/dotnet/Package/Services/ServiceTemplate.cs.twig

@@ -26,6 +26,13 @@ namespace {{ spec.title | caseUcfirst }}.Services
         /// </para>
         {%~ endif %}
         /// </summary>
+        {%~ if method.deprecated %}
+        {%~ if method.since and method.replaceWith %}
+        [Obsolete("This API is deprecated since {{ method.since }} and uses outdated terminologies. Please use `{{ method.replaceWith | capitalizeFirst }}` instead.")]
+        {%~ else %}
+        [Obsolete("This API is deprecated.")]
+        {%~ endif %}
+        {%~ endif %}
         public Task{% if method.type == "webAuth" %}<String>{% else %}<{{ utils.resultType(spec.title, method) }}>{% endif %} {{ method.name | caseUcfirst }}({{ utils.method_parameters(method.parameters, method.consumes) }})
         {
             var apiPath = "{{ method.path }}"{% if method.parameters.path | length == 0 %};{% endif %}

templates/flutter/lib/services/service.dart.twig

@@ -18,6 +18,13 @@ class {{ service.name | caseUcfirst }} extends Service {
 {%~ if method.description %}
 {{ method.description|dartComment }}
 {% endif %}
+{%~ if method.deprecated %}
+{%~ if method.since and method.replaceWith %}
+    @Deprecated('This API is deprecated since {{ method.since }} and uses outdated terminologies. Please use `{{ method.replaceWith | capitalizeFirst }}` instead.')
+{%~ else %}
+    @Deprecated('This API is deprecated.')
+{%~ endif %}
+{%~ endif %}
     {% if method.type == 'webAuth' %}Future{% elseif method.type == 'location' %}Future<Uint8List>{% else %}{% if method.responseModel and method.responseModel != 'any' %}Future<models.{{method.responseModel | caseUcfirst | overrideIdentifier}}>{% else %}Future{% endif %}{% endif %} {{ method.name | caseCamel | overrideIdentifier }}({{ _self.method_parameters(method.parameters.all, method.consumes) }}) async {
         {% if method.parameters.path | length > 0 %}final{% else %}const{% endif %} String apiPath = '{{ method.path }}'{% for parameter in method.parameters.path %}.replaceAll('{{ '{' }}{{ parameter.name | caseCamel }}{{ '}' }}', {{ parameter.name | caseCamel | overrideIdentifier }}{% if parameter.enumValues | length > 0  %}.value{% endif %}){% endfor %};
 

templates/go/services/service.go.twig

@@ -87,6 +87,14 @@ func (srv *{{ service.name | caseUcfirst }}) With{{ method.name | caseUcfirst }}
 {% else %}
 // {{ method.name | caseUcfirst }}
 {% endif %}
+{% if method.deprecated %}
+//
+{%~ if method.since and method.replaceWith %}
+// Deprecated: This API is deprecated since {{ method.since }} and uses outdated terminologies. Please use `{{ method.replaceWith | capitalizeFirst }}` instead.
+{%~ else %}
+// Deprecated: This API is deprecated.
+{%~ endif %}
+{% endif %}
 func (srv *{{ service.name | caseUcfirst }}) {{ method.name | caseUcfirst }}({{ params }})(*{{ method | returnType(spec, spec.title | caseLower) }}, error) {
 {% if method.parameters.path|length > 0 %}
 	r := strings.NewReplacer({% for parameter in method.parameters.path %}"{{ '{' }}{{ parameter.name | caseCamel }}{{ '}' }}", {{ parameter.name | caseUcfirst }}{% if not loop.last %}, {% endif %}{% endfor %})

templates/kotlin/src/main/kotlin/io/appwrite/services/ServiceTemplate.kt.twig

@@ -30,6 +30,19 @@ class {{ service.name | caseUcfirst }}(client: Client) : Service(client) {
     {%~ endfor %}
      * @return [{{ method | returnType(spec, sdk.namespace | caseDot) | raw }}]
      */
+    {%~ if method.deprecated %}
+    {%~ if method.since and method.replaceWith %}
+    @Deprecated(
+        message = "This API is deprecated since {{ method.since }} and uses outdated terminologies. Please use `{{ method.replaceWith | capitalizeFirst }}` instead.",
+        replaceWith = ReplaceWith("{{ sdk.namespace | caseDot }}.services.{{ method.replaceWith | capitalizeFirst }}"),
+        since = "{{ method.since }}"
+    )
+    {%~ else %}
+    @Deprecated(
+        message = "This API is deprecated."
+    )
+    {%~ endif %}
+    {%~ endif %}
     {%~ if method.parameters.all | reduce((carry, param) => carry or not param.required) %}
     @JvmOverloads
     {%~ endif %}
@@ -91,6 +104,19 @@ class {{ service.name | caseUcfirst }}(client: Client) : Service(client) {
     {%~ endfor %}
      * @return [{{ method | returnType(spec, sdk.namespace | caseDot) | raw }}]
      */
+    {%~ if method.deprecated %}
+    {%~ if method.since and method.replaceWith %}
+    @Deprecated(
+        message = "This API is deprecated since {{ method.since }} and uses outdated terminologies. Please use `{{ method.replaceWith | capitalizeFirst }}` instead.",
+        replaceWith = ReplaceWith("{{ sdk.namespace | caseDot }}.services.{{ method.replaceWith | capitalizeFirst }}"),
+        since = "{{ method.since }}"
+    )
+    {%~ else %}
+    @Deprecated(
+        message = "This API is deprecated."
+    )
+    {%~ endif %}
+    {%~ endif %}
     {%~ if method.parameters.all | reduce((carry, param) => carry or not param.required) %}
     @JvmOverloads
     {%~ endif %}

templates/node/src/services/template.ts.twig

@@ -27,14 +27,21 @@ export class {{ service.name | caseUcfirst }} {
     {%~ for method in service.methods %}
     /**
     {%~ if method.description %}
-     * {{ method.description }}
+     * {{ method.description | replace({'\n': '\n     * '}) }}
     {%~ endif %}
      *
     {%~ for parameter in method.parameters.all %}
      * @param {{ '{' }}{{ parameter | getPropertyType(method) | raw }}{{ '}' }} {{ parameter.name | caseCamel | escapeKeyword }}
     {%~ endfor %}
      * @throws {{ '{' }}{{ spec.title | caseUcfirst}}Exception}
      * @returns {{ '{' }}{{ method | getReturn(spec) | raw }}{{ '}' }}
+    {%~ if method.deprecated %}
+    {%~ if method.since and method.replaceWith %}
+     * @deprecated This API is deprecated since {{ method.since }} and uses outdated terminologies.{% if method.replaceWith %} Please use `{{ method.replaceWith | capitalizeFirst }}` instead.{% endif %} 
+    {%~ else %}
+     * @deprecated This API is deprecated.
+    {%~ endif %}
+    {%~ endif %}
      */
     {{ method.name | caseCamel }}{{ method.responseModel | getGenerics(spec) | raw }}({% for parameter in method.parameters.all %}{{ parameter.name | caseCamel | escapeKeyword }}{% if not parameter.required or parameter.nullable %}?{% endif %}: {{ parameter | getPropertyType(method) | raw }}{% if not loop.last %}, {% endif %}{% endfor %}{% if 'multipart/form-data' in method.consumes %}, onProgress = (progress: UploadProgress) => {}{% endif %}): {{ method | getReturn(spec) | raw }} {
         {%~ for parameter in method.parameters.all %}
@@ -94,5 +101,8 @@ export class {{ service.name | caseUcfirst }} {
         );
         {%~ endif %}
     }
+{% if not loop.last %}
+
+{% endif %}
     {%~ endfor %}
 }

templates/php/src/Services/Service.php.twig

@@ -31,6 +31,7 @@ class {{ service.name | caseUcfirst }} extends Service
      }
 
 {% for method in service.methods %}
+{% set deprecated_message = '' %}
     /**
 {% if method.description %}
 {{ method.description|comment1 }}
@@ -41,6 +42,17 @@ class {{ service.name | caseUcfirst }} extends Service
 {% endfor %}
      * @throws {{spec.title | caseUcfirst}}Exception
      * @return {{ method | getReturn }}
+{% if method.deprecated %}
+     *
+{%~ if method.since and method.replaceWith %}
+     * @deprecated This API is deprecated since {{ method.since }} and uses outdated terminologies. Please use `{{ method.replaceWith | split('.') | last | caseCamel }}` instead.
+{%~ else %}
+     * @deprecated This API is deprecated.
+{%~ endif %}
+{% if method.replaceWith %}
+     * @see {{ method.replaceWith | replace({'.': '::'}) | capitalizeFirst }}
+{% endif %}
+{% endif %}
      */
     public function {{ method.name | caseCamel }}({% for parameter in method.parameters.all %}{% if not parameter.required or parameter.nullable %}?{% endif %}{{ parameter | typeName }} ${{ parameter.name | caseCamel | escapeKeyword }}{% if not parameter.required %} = null{% endif %}{% if not loop.last %}, {% endif %}{% endfor %}{% if 'multipart/form-data' in method.consumes %}, callable $onProgress = null{% endif %}): {{ method | getReturn }}
     {

templates/python/package/services/service.py.twig

@@ -34,6 +34,16 @@ class {{ service.name | caseUcfirst }}(Service):
 
 {% if method.parameters.all|length > 0 or 'multipart/form-data' in method.consumes %}
 
+{% if method.deprecated %}
+{%~ if method.since and method.replaceWith %}
+        .. deprecated::{{ method.since }}
+            This API is deprecated since {{ method.since }} and uses outdated terminologies.{% if method.replaceWith %} Please use `{{ method.replaceWith | caseSnakeExceptFirstDot }}` instead.{% endif %} 
+{%~ else %}
+        .. deprecated::
+            This API is deprecated.
+{%~ endif %}
+{% endif %}
+
         Parameters
         ----------
         {% for parameter in method.parameters.all %}{{ parameter.name | escapeKeyword | caseSnake }} : {{ parameter | getPropertyType(method) | raw }}