feat: add javadocs for operations and deprecate old paginator methods (…

…#561)
ExpediaGroup · May 29, 2024 · b22da4c · b22da4c
1 parent af107eb
commit b22da4c
Show file tree

Hide file tree

Showing 5 changed files with 63 additions and 47 deletions.
diff --git a/generator/openapi/src/main/kotlin/com/expediagroup/sdk/generators/openapi/MustacheHelpers.kt b/generator/openapi/src/main/kotlin/com/expediagroup/sdk/generators/openapi/MustacheHelpers.kt
@@ -34,23 +34,14 @@ val fallbackBody = fun(dataType: String): String {
 }
 
 val mustacheHelpers = mapOf(
-    "paginator" to {
+    "isPaginatable" to {
         Mustache.Lambda { fragment, writer ->
             val operation = fragment.context() as CodegenOperation
             val paginationHeaders = listOf("Pagination-Total-Results", "Link")
             val availableHeaders = operation.responses.find { it.code == "200" }?.headers?.filter { it.baseName in paginationHeaders }
             if (availableHeaders?.size == paginationHeaders.size) {
-                writer.write("@JvmOverloads")
-                writer.write(System.lineSeparator())
-                writer.write("fun getPaginator(operation: ${operation.operationIdCamelCase}Operation): ResponsePaginator<${operation.returnType}> {")
-                writer.write(System.lineSeparator())
-                writer.write("val response = execute(operation)")
-                writer.write(System.lineSeparator())
-                writer.write("return ResponsePaginator(this, response, ")
-                writer.write(fallbackBody("${operation.returnType}"))
-                writer.write(") { it.body<${operation.returnType}>() }")
-                writer.write(System.lineSeparator())
-                writer.write("}")
+                val context = mapOf("fallbackBody" to fallbackBody(operation.returnType))
+                fragment.execute(context, writer)
             }
         }
     },
@@ -122,17 +113,5 @@ val mustacheHelpers = mapOf(
             }
             writer.write(stringBuilder.toString())
         }
-    },
-    "fallbackBody" to {
-        Mustache.Lambda { fragment, writer ->
-            val dataType: String = fragment.context() as String
-            if (dataType.startsWith("kotlin.collections.List")) {
-                writer.write("emptyList()")
-            } else if (dataType.startsWith("kotlin.collections.Map")) {
-                writer.write("emptyMap()")
-            } else if (dataType.startsWith("kotlin.collections.Set")) {
-                writer.write("emptySet()")
-            }
-        }
     }
 )
diff --git a/generator/openapi/src/main/resources/templates/expediagroup-sdk/api.mustache b/generator/openapi/src/main/resources/templates/expediagroup-sdk/api.mustache
@@ -14,6 +14,21 @@ import com.expediagroup.sdk.core.model.Operation
 
 {{#operations}}
     {{#operation}}
+        /**
+        * {{{summary}}}
+        {{#hasBodyParam}}
+            * @property requestBody [{{#bodyParam}}{{dataType}}{{/bodyParam}}]
+        {{/hasBodyParam}}
+        {{#hasPathParams}}
+            * @property params [{{classname}}Params]
+        {{/hasPathParams}}
+        {{^hasPathParams}}{{#hasHeaderParams}}
+            * @property params [{{classname}}Params]
+        {{/hasHeaderParams}}{{/hasPathParams}}
+        {{^hasPathParams}}{{^hasHeaderParams}}{{#hasQueryParams}}
+            * @property params [{{classname}}Params]
+        {{/hasQueryParams}}{{/hasHeaderParams}}{{/hasPathParams}}
+        */
         class {{classname}}(
             {{#hasBodyParam}}
                 requestBody: {{#bodyParam}}{{dataType}}{{/bodyParam}}{{^required}}?{{/required}},

diff --git a/generator/openapi/src/main/resources/templates/expediagroup-sdk/client.mustache b/generator/openapi/src/main/resources/templates/expediagroup-sdk/client.mustache
@@ -68,6 +68,13 @@ class {{#lambda.titlecase}}{{namespace}}{{/lambda.titlecase}}Client private cons
     }
 
     {{#apiInfo}}{{#apis}}{{#operations}}{{#operation}}
+        /**
+        * {{{summary}}}
+        * {{{notes}}}
+        * @param operation [{{operationIdCamelCase}}Operation]
+        {{#throwsExceptions}}{{/throwsExceptions}}
+        * @return a [Response] object with a body of type {{{returnType}}}{{^returnType}}Nothing{{/returnType}}
+        */
         fun execute(operation: {{operationIdCamelCase}}Operation) : {{#returnType}}Response<{{{returnType}}}>{{/returnType}}{{^returnType}}Response<Nothing>{{/returnType}} {
             return execute<
                 {{#bodyParam}}{{dataType}}{{/bodyParam}}{{^hasBodyParam}}Nothing{{/hasBodyParam}},
@@ -109,8 +116,6 @@ class {{#lambda.titlecase}}{{namespace}}{{/lambda.titlecase}}Client private cons
             return execute(operation)
         }
 
-        {{#paginator}}{{/paginator}}
-
         {{^isKotlin}}
             /**
             * {{{summary}}}
@@ -150,7 +155,9 @@ class {{#lambda.titlecase}}{{namespace}}{{/lambda.titlecase}}Client private cons
                 }
             }
         {{/isKotlin}}
-        {{/operation}}
-        {{>client/paginatorMethods}}
-    {{/operations}}{{/apis}}{{/apiInfo}}
+
+        {{#isPaginatable}}
+            {{>client/paginatorMethods}}
+        {{/isPaginatable}}
+    {{/operation}}{{/operations}}{{/apis}}{{/apiInfo}}
 }
diff --git a/...or/openapi/src/main/resources/templates/expediagroup-sdk/client/paginatorMethods.mustache b/...or/openapi/src/main/resources/templates/expediagroup-sdk/client/paginatorMethods.mustache
@@ -1,20 +1,21 @@
-{{#operation}}
-    {{#vendorExtensions}}
-        {{#x-sdk-paginated}}
-            {{#returnType}}
-                @JvmOverloads
-                fun {{operationId}}Paginator({{>client/apiParamsDecleration}}): Paginator<{{{returnType}}}> {
-                    val response = {{operationId}}WithResponse({{>client/apiParamsPassed}})
-                    return Paginator(this, response, {{#fallbackBody}}{{/fallbackBody}}) { it.body<{{{returnType}}}>() }
-                }
+{{#returnType}}
+    @JvmOverloads
+    fun getPaginator(operation: {{operationIdCamelCase}}Operation): ResponsePaginator<{{{returnType}}}> {
+        val response = execute(operation)
+        return ResponsePaginator(this, response, {{fallbackBody}}) { it.body<{{{returnType}}}>() }
+    }
 
-                @JvmOverloads
-                fun {{operationId}}PaginatorWithResponse({{>client/apiParamsDecleration}}): ResponsePaginator<{{{returnType}}}> {
-                    val response = {{operationId}}WithResponse({{>client/apiParamsPassed}})
-                    return ResponsePaginator(this, response, {{#fallbackBody}}{{/fallbackBody}}) { it.body<{{{returnType}}}>() }
-                }
+    @JvmOverloads
+    @Deprecated("Use getPaginator method instead", ReplaceWith("getPaginator(operation: {{operationIdCamelCase}}Operation)"))
+    fun {{operationId}}Paginator({{>client/apiParamsDecleration}}): Paginator<{{{returnType}}}> {
+        val response = {{operationId}}WithResponse({{>client/apiParamsPassed}})
+        return Paginator(this, response, {{fallbackBody}}) { it.body<{{{returnType}}}>() }
+    }
 
-            {{/returnType}}
-        {{/x-sdk-paginated}}
-    {{/vendorExtensions}}
-{{/operation}}
+    @JvmOverloads
+    @Deprecated("Use getPaginator method instead", ReplaceWith("getPaginator(operation: {{operationIdCamelCase}}Operation)"))
+    fun {{operationId}}PaginatorWithResponse({{>client/apiParamsDecleration}}): ResponsePaginator<{{{returnType}}}> {
+        val response = {{operationId}}WithResponse({{>client/apiParamsPassed}})
+        return ResponsePaginator(this, response, {{fallbackBody}}) { it.body<{{{returnType}}}>() }
+    }
+{{/returnType}}
diff --git a/generator/openapi/src/main/resources/templates/expediagroup-sdk/operation_params.mustache b/generator/openapi/src/main/resources/templates/expediagroup-sdk/operation_params.mustache
@@ -6,6 +6,11 @@ import com.expediagroup.sdk.core.model.OperationParams
 
 {{#operations}}
     {{#operation}}
+        /**
+        {{#allParams}}
+            * @property {{{paramName}}} {{{description}}}
+        {{/allParams}}
+        */
         data class {{classname}}Params(
             {{#pathParams}}{{>modelMutable}} {{>client/apiParam}}{{^-last}}, {{/-last}}{{/pathParams}}
             {{#hasPathParams}}{{#hasHeaderParams}}, {{/hasHeaderParams}}{{/hasPathParams}}
@@ -32,12 +37,21 @@ import com.expediagroup.sdk.core.model.OperationParams
                 {{/queryParams}}
             ) {
                 {{#pathParams}}
+                    /**
+                    * @param {{{paramName}}} {{{description}}}
+                    */
                     fun {{{paramName}}}({{{paramName}}}: {{{dataType}}}) = apply { this.{{{paramName}}} = {{{paramName}}} }
                 {{/pathParams}}
                 {{#headerParams}}
+                    /**
+                    * @param {{{paramName}}} {{{description}}}
+                    */
                     fun {{{paramName}}}({{{paramName}}}: {{{dataType}}}) = apply { this.{{{paramName}}} = {{{paramName}}} }
                 {{/headerParams}}
                 {{#queryParams}}
+                    /**
+                    * @param {{{paramName}}} {{{description}}}
+                    */
                     fun {{{paramName}}}({{{paramName}}}: {{{dataType}}}) = apply { this.{{{paramName}}} = {{{paramName}}} }
                 {{/queryParams}}