From b22da4c6850cca6bb1adc8f52128b45d2aad257c Mon Sep 17 00:00:00 2001 From: Nasser Anssari Date: Wed, 29 May 2024 17:47:43 +0300 Subject: [PATCH] feat: add javadocs for operations and deprecate old paginator methods (#561) --- .../sdk/generators/openapi/MustacheHelpers.kt | 27 ++------------ .../templates/expediagroup-sdk/api.mustache | 15 ++++++++ .../expediagroup-sdk/client.mustache | 17 ++++++--- .../client/paginatorMethods.mustache | 37 ++++++++++--------- .../operation_params.mustache | 14 +++++++ 5 files changed, 63 insertions(+), 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 index 0bdd36fc9..d6528f189 100644 --- 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 index f22366d36..118c4be86 100644 --- 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 index e3b4668d9..b7e5d979d 100644 --- 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{{/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}} } \ No newline at end of file diff --git a/generator/openapi/src/main/resources/templates/expediagroup-sdk/client/paginatorMethods.mustache b/generator/openapi/src/main/resources/templates/expediagroup-sdk/client/paginatorMethods.mustache index 3f347d519..2dd089681 100644 --- a/generator/openapi/src/main/resources/templates/expediagroup-sdk/client/paginatorMethods.mustache +++ b/generator/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}} \ No newline at end of file + @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}} \ No newline at end of file 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 index 77d1df191..1b213c7a8 100644 --- 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}}