Kotlin multiplatform client

Created by: andrewemery

Support for the generation of Kotlin Multiplatform clients.

Background

The kotlin language defined in the Swagger Codegen project currently generates a Kotlin client that can run on the JVM. Somewhat recently, JetBrains introduced Kotlin Multiplatform, a platform that provides the ability to share code between various platforms: JVM, JS, iOS, Windows, etc. This pull request adds the ability to generate a Kotlin Multiplatform client.

Library

The pull request includes Kotlin Multiplatform generation under the kotlin language and introduces two library options:

1. jvm: (default) to target the existing Kotlin JVM generation.
2. multiplatform: to target Kotlin Multiplatform generation.

Limitations

The current pull request only currently adds support for JVM and iOS platforms but support for other platforms should be trivial to add.

At present, date and date-time objects are rendered as strings. No attempt is made to integrate any third-party date/time libraries.

Tests

The current implementation doesn't include any tests beyond those already included as part of the kotlin language implementation. A test project can be found here that generates the petstore sample and includes tests to verify the correctness of the implementation.

Comments welcome.

References

https://github.com/OpenAPITools/openapi-generator/issues/3899 https://github.com/andrewemery/openapi-generator-kotlin-multiplatform-petstore

bin/openapi3/kotlin-client-petstore-multiplatform.sh

+#!/bin/sh
+
+SCRIPT="$0"
+echo "# START SCRIPT: $SCRIPT"
+
+while [ -h "$SCRIPT" ] ; do
+  ls=$(ls -ld "$SCRIPT")
+  link=$(expr "$ls" : '.*-> \(.*\)$')
+  if expr "$link" : '/.*' > /dev/null; then
+    SCRIPT="$link"
+  else
+    SCRIPT=$(dirname "$SCRIPT")/"$link"
+  fi
+done
+
+if [ ! -d "${APP_DIR}" ]; then
+  APP_DIR=$(dirname "$SCRIPT")/..
+  APP_DIR=$(cd "${APP_DIR}"; pwd)
+fi
+
+executable="./modules/openapi-generator-cli/target/openapi-generator-cli.jar"
+
+if [ ! -f "$executable" ]
+then
+  mvn clean package
+fi
+
+export JAVA_OPTS="${JAVA_OPTS} -Xmx1024M -DloggerPath=conf/log4j.properties"
+ags="generate -i modules/openapi-generator/src/test/resources/3_0/petstore-with-fake-endpoints-models-for-testing.yaml -t modules/openapi-generator/src/main/resources/kotlin-client -g kotlin --artifact-id kotlin-client-petstore-multiplatform --library multiplatform -o samples/openapi3/client/petstore/kotlin-multiplatform $@"
+
+echo "Cleaning previously generated files if any from samples/openapi3/client/petstore/kotlin-multiplatform"
+rm -rf samples/openapi3/client/petstore/kotlin-multiplatform
+
+echo "Generating Kotling client..."
+java $JAVA_OPTS -jar $executable $ags

bin/windows/kotlin-client-petstore-multiplatform.bat

+set executable=.\modules\openapi-generator-cli\target\openapi-generator-cli.jar
+
+If Not Exist %executable% (
+  mvn clean package
+)
+
+REM set JAVA_OPTS=%JAVA_OPTS% -Xmx1024M -DloggerPath=conf/log4j.properties
+set ags=generate  --artifact-id "kotlin-client-petstore-multiplatform" -i modules\openapi-generator\src\test\resources\2_0\petstore.yaml -g kotlin --library multiplatform -o samples\client\petstore\kotlin-multiplatform
+
+java %JAVA_OPTS% -jar %executable% %ags%

bin/kotlin-client-petstore-multiplatform.sh

+#!/bin/sh
+
+SCRIPT="$0"
+echo "# START SCRIPT: $SCRIPT"
+
+while [ -h "$SCRIPT" ] ; do
+  ls=$(ls -ld "$SCRIPT")
+  link=$(expr "$ls" : '.*-> \(.*\)$')
+  if expr "$link" : '/.*' > /dev/null; then
+    SCRIPT="$link"
+  else
+    SCRIPT=$(dirname "$SCRIPT")/"$link"
+  fi
+done
+
+if [ ! -d "${APP_DIR}" ]; then
+  APP_DIR=$(dirname "$SCRIPT")/..
+  APP_DIR=$(cd "${APP_DIR}"; pwd)
+fi
+
+executable="./modules/openapi-generator-cli/target/openapi-generator-cli.jar"
+
+if [ ! -f "$executable" ]
+then
+  mvn -B clean package
+fi
+
+# if you've executed sbt assembly previously it will use that instead.
+export JAVA_OPTS="${JAVA_OPTS} -Xmx1024M -DloggerPath=conf/log4j.properties"
+ags="generate -t modules/openapi-generator/src/main/resources/kotlin-client -i modules/openapi-generator/src/test/resources/2_0/petstore.yaml -g kotlin --artifact-id kotlin-client-petstore-multiplatform --library multiplatform -o samples/client/petstore/kotlin-multiplatform $@"
+
+java ${JAVA_OPTS} -jar ${executable} ${ags}

docs/generators/kotlin.md

@@ -16,5 +16,6 @@ sidebar_label: kotlin
 |enumPropertyNaming|Naming convention for enum properties: 'camelCase', 'PascalCase', 'snake_case', 'UPPERCASE', and 'original'| |camelCase|
 |serializationLibrary|What serialization library to use: 'moshi' (default), or 'gson'| |moshi|
 |parcelizeModels|toggle "@Parcelize" for generated models| |null|
-|dateLibrary|Option. Date library to use|<dl><dt>**string**</dt><dd>String</dd><dt>**java8**</dt><dd>Java 8 native JSR310</dd><dt>**threetenbp**</dt><dd>Threetenbp</dd><dl>|java8|
+|dateLibrary|Option. Date library to use|<dl><dt>**string**</dt><dd>String</dd><dt>**java8**</dt><dd>Java 8 native JSR310 (jvm only)</dd><dt>**threetenbp**</dt><dd>Threetenbp (jvm only)</dd><dl>|java8|
 |collectionType|Option. Collection type to use|<dl><dt>**array**</dt><dd>kotlin.Array</dd><dt>**list**</dt><dd>kotlin.collections.List</dd><dl>|array|
+|library|Library template (sub-template) to use|<dl><dt>**jvm**</dt><dd>Platform: Java Virtual Machine. HTTP client: OkHttp 2.7.5. JSON processing: Gson 2.8.1.</dd><dt>**multiplatform**</dt><dd>Platform: Kotlin multiplatform. HTTP client: Ktor 1.2.4. JSON processing: Kotlinx Serialization: 0.12.0.</dd><dl>|jvm|

modules/openapi-generator/src/main/java/org/openapitools/codegen/languages/KotlinClientCodegen.java

@@ -19,21 +19,42 @@ package org.openapitools.codegen.languages;
 
 import org.openapitools.codegen.CliOption;
 import org.openapitools.codegen.CodegenConstants;
+import org.openapitools.codegen.CodegenModel;
+import org.openapitools.codegen.CodegenOperation;
+import org.openapitools.codegen.CodegenProperty;
 import org.openapitools.codegen.CodegenType;
 import org.openapitools.codegen.SupportingFile;
 
 import java.io.File;
 import java.util.HashMap;
+import java.util.HashSet;
+import java.util.Iterator;
+import java.util.List;
 import java.util.Map;
+import java.util.Set;
+import java.util.regex.Pattern;
 
 public class KotlinClientCodegen extends AbstractKotlinCodegen {
 
+    protected static final String VENDOR_EXTENSION_ESCAPED_NAME = "x-escapedName";
+
+    protected static final String JVM = "jvm";
+    protected static final String MULTIPLATFORM = "multiplatform";
+
     public static final String DATE_LIBRARY = "dateLibrary";
     public static final String COLLECTION_TYPE = "collectionType";
 
     protected String dateLibrary = DateLibrary.JAVA8.value;
     protected String collectionType = CollectionType.ARRAY.value;
 
+    // https://kotlinlang.org/docs/reference/grammar.html#Identifier
+    protected static final Pattern IDENTIFIER_PATTERN =
+            Pattern.compile("[\\p{Ll}\\p{Lm}\\p{Lo}\\p{Lt}\\p{Lu}\\p{Nl}_][\\p{Ll}\\p{Lm}\\p{Lo}\\p{Lt}\\p{Lu}\\p{Nl}\\p{Nd}_]*");
+
+    // https://kotlinlang.org/docs/reference/grammar.html#Identifier
+    protected static final String IDENTIFIER_REPLACEMENTS =
+            "[.;:/\\[\\]<>]";
+
     public enum DateLibrary {
         STRING("string"),
         THREETENBP("threetenbp"),
@@ -81,9 +102,9 @@ public class KotlinClientCodegen extends AbstractKotlinCodegen {
 
         CliOption dateLibrary = new CliOption(DATE_LIBRARY, "Option. Date library to use");
         Map<String, String> dateOptions = new HashMap<>();
-        dateOptions.put(DateLibrary.THREETENBP.value, "Threetenbp");
+        dateOptions.put(DateLibrary.THREETENBP.value, "Threetenbp (jvm only)");
         dateOptions.put(DateLibrary.STRING.value, "String");
-        dateOptions.put(DateLibrary.JAVA8.value, "Java 8 native JSR310");
+        dateOptions.put(DateLibrary.JAVA8.value, "Java 8 native JSR310 (jvm only)");
         dateLibrary.setEnum(dateOptions);
         dateLibrary.setDefault(this.dateLibrary);
         cliOptions.add(dateLibrary);
@@ -95,6 +116,15 @@ public class KotlinClientCodegen extends AbstractKotlinCodegen {
         collectionType.setEnum(collectionOptions);
         collectionType.setDefault(this.collectionType);
         cliOptions.add(collectionType);
+
+        supportedLibraries.put(JVM, "Platform: Java Virtual Machine. HTTP client: OkHttp 2.7.5. JSON processing: Gson 2.8.1.");
+        supportedLibraries.put(MULTIPLATFORM, "Platform: Kotlin multiplatform. HTTP client: Ktor 1.2.4. JSON processing: Kotlinx Serialization: 0.12.0.");
+
+        CliOption libraryOption = new CliOption(CodegenConstants.LIBRARY, "Library template (sub-template) to use");
+        libraryOption.setEnum(supportedLibraries);
+        libraryOption.setDefault(JVM);
+        cliOptions.add(libraryOption);
+        setLibrary(JVM);
     }
 
     public CodegenType getTag() {
@@ -121,10 +151,80 @@ public class KotlinClientCodegen extends AbstractKotlinCodegen {
     public void processOpts() {
         super.processOpts();
 
+        if (MULTIPLATFORM.equals(getLibrary())) {
+            sourceFolder = "src/commonMain/kotlin";
+        }
+
+        // infrastructure destination folder
+        final String infrastructureFolder = (sourceFolder + File.separator + packageName + File.separator + "infrastructure").replace(".", "/");
+
+        // additional properties
         if (additionalProperties.containsKey(DATE_LIBRARY)) {
             setDateLibrary(additionalProperties.get(DATE_LIBRARY).toString());
         }
 
+        // common (jvm/multiplatform) supporting files
+        supportingFiles.add(new SupportingFile("README.mustache", "", "README.md"));
+        supportingFiles.add(new SupportingFile("build.gradle.mustache", "", "build.gradle"));
+        supportingFiles.add(new SupportingFile("settings.gradle.mustache", "", "settings.gradle"));
+        supportingFiles.add(new SupportingFile("infrastructure/ApiClient.kt.mustache", infrastructureFolder, "ApiClient.kt"));
+        supportingFiles.add(new SupportingFile("infrastructure/ApiAbstractions.kt.mustache", infrastructureFolder, "ApiAbstractions.kt"));
+        supportingFiles.add(new SupportingFile("infrastructure/RequestConfig.kt.mustache", infrastructureFolder, "RequestConfig.kt"));
+        supportingFiles.add(new SupportingFile("infrastructure/RequestMethod.kt.mustache", infrastructureFolder, "RequestMethod.kt"));
+
+        if (JVM.equals(getLibrary())) {
+            additionalProperties.put(JVM, true);
+
+            // jvm specific supporting files
+            supportingFiles.add(new SupportingFile("infrastructure/ApplicationDelegates.kt.mustache", infrastructureFolder, "ApplicationDelegates.kt"));
+            supportingFiles.add(new SupportingFile("infrastructure/Errors.kt.mustache", infrastructureFolder, "Errors.kt"));
+            supportingFiles.add(new SupportingFile("infrastructure/ResponseExtensions.kt.mustache", infrastructureFolder, "ResponseExtensions.kt"));
+            supportingFiles.add(new SupportingFile("infrastructure/Serializer.kt.mustache", infrastructureFolder, "Serializer.kt"));
+            supportingFiles.add(new SupportingFile("infrastructure/ApiInfrastructureResponse.kt.mustache", infrastructureFolder, "ApiInfrastructureResponse.kt"));
+            supportingFiles.add(new SupportingFile("infrastructure/ByteArrayAdapter.kt.mustache", infrastructureFolder, "ByteArrayAdapter.kt"));
+            supportingFiles.add(new SupportingFile("infrastructure/LocalDateAdapter.kt.mustache", infrastructureFolder, "LocalDateAdapter.kt"));
+            supportingFiles.add(new SupportingFile("infrastructure/LocalDateTimeAdapter.kt.mustache", infrastructureFolder, "LocalDateTimeAdapter.kt"));
+            supportingFiles.add(new SupportingFile("infrastructure/UUIDAdapter.kt.mustache", infrastructureFolder, "UUIDAdapter.kt"));
+
+        } else if (MULTIPLATFORM.equals(getLibrary())) {
+            additionalProperties.put(MULTIPLATFORM, true);
+            setDateLibrary(DateLibrary.STRING.value);
+
+            // multiplatform default includes
+            defaultIncludes.add("io.ktor.client.request.forms.InputProvider");
+
+            // multiplatform type mapping
+            typeMapping.put("number", "kotlin.Double");
+            typeMapping.put("file", "InputProvider");
+
+            // multiplatform import mapping
+            importMapping.put("BigDecimal", "kotlin.Double");
+            importMapping.put("UUID", "kotlin.String");
+            importMapping.put("URI", "kotlin.String");
+            importMapping.put("InputProvider", "io.ktor.client.request.forms.InputProvider");
+            importMapping.put("File", "io.ktor.client.request.forms.InputProvider");
+            importMapping.put("Timestamp", "kotlin.String");
+            importMapping.put("LocalDateTime", "kotlin.String");
+            importMapping.put("LocalDate", "kotlin.String");
+            importMapping.put("LocalTime", "kotlin.String");
+
+            // multiplatform specific supporting files
+            supportingFiles.add(new SupportingFile("infrastructure/HttpResponse.kt.mustache", infrastructureFolder, "HttpResponse.kt"));
+
+            // multiplatform specific testing files
+            final String testFolder = (sourceFolder + File.separator + packageName + File.separator + "infrastructure").replace(".", "/");
+            supportingFiles.add(new SupportingFile("commonTest/coroutine.mustache", "src/commonTest/kotlin/util", "Coroutine.kt"));
+            supportingFiles.add(new SupportingFile("iosTest/coroutine.mustache", "src/iosTest/kotlin/util", "Coroutine.kt"));
+            supportingFiles.add(new SupportingFile("jvmTest/coroutine.mustache", "src/jvmTest/kotlin/util", "Coroutine.kt"));
+
+            // gradle wrapper supporting files
+            supportingFiles.add(new SupportingFile("gradlew.mustache", "", "gradlew"));
+            supportingFiles.add(new SupportingFile("gradlew.bat.mustache", "", "gradlew.bat"));
+            supportingFiles.add(new SupportingFile("gradle-wrapper.properties.mustache", "gradle.wrapper".replace(".", File.separator), "gradle-wrapper.properties"));
+            supportingFiles.add(new SupportingFile("gradle-wrapper.jar", "gradle.wrapper".replace(".", File.separator), "gradle-wrapper.jar"));
+        }
+
+        // date library processing
         if (DateLibrary.THREETENBP.value.equals(dateLibrary)) {
             additionalProperties.put(DateLibrary.THREETENBP.value, true);
             typeMapping.put("date", "LocalDate");
@@ -151,25 +251,83 @@ public class KotlinClientCodegen extends AbstractKotlinCodegen {
             typeMapping.put("list", "kotlin.collections.List");
             additionalProperties.put("isList", true);
         }
+    }
 
-        supportingFiles.add(new SupportingFile("README.mustache", "", "README.md"));
-        supportingFiles.add(new SupportingFile("build.gradle.mustache", "", "build.gradle"));
-        supportingFiles.add(new SupportingFile("settings.gradle.mustache", "", "settings.gradle"));
+    @Override
+    public Map<String, Object> postProcessModels(Map<String, Object> objs) {
+        objs = super.postProcessModels(objs);
+        return postProcessModelsEscapeNames(objs);
+    }
 
-        final String infrastructureFolder = (sourceFolder + File.separator + packageName + File.separator + "infrastructure").replace(".", "/");
+    @SuppressWarnings("unchecked")
+    private static Map<String, Object> postProcessModelsEscapeNames(Map<String, Object> objs) {
+        List<Object> models = (List<Object>) objs.get("models");
+        for (Object _mo : models) {
+            Map<String, Object> mo = (Map<String, Object>) _mo;
+            CodegenModel cm = (CodegenModel) mo.get("model");
 
-        supportingFiles.add(new SupportingFile("infrastructure/ApiClient.kt.mustache", infrastructureFolder, "ApiClient.kt"));
-        supportingFiles.add(new SupportingFile("infrastructure/ApiAbstractions.kt.mustache", infrastructureFolder, "ApiAbstractions.kt"));
-        supportingFiles.add(new SupportingFile("infrastructure/ApiInfrastructureResponse.kt.mustache", infrastructureFolder, "ApiInfrastructureResponse.kt"));
-        supportingFiles.add(new SupportingFile("infrastructure/ApplicationDelegates.kt.mustache", infrastructureFolder, "ApplicationDelegates.kt"));
-        supportingFiles.add(new SupportingFile("infrastructure/RequestConfig.kt.mustache", infrastructureFolder, "RequestConfig.kt"));
-        supportingFiles.add(new SupportingFile("infrastructure/RequestMethod.kt.mustache", infrastructureFolder, "RequestMethod.kt"));
-        supportingFiles.add(new SupportingFile("infrastructure/ResponseExtensions.kt.mustache", infrastructureFolder, "ResponseExtensions.kt"));
-        supportingFiles.add(new SupportingFile("infrastructure/Serializer.kt.mustache", infrastructureFolder, "Serializer.kt"));
-        supportingFiles.add(new SupportingFile("infrastructure/Errors.kt.mustache", infrastructureFolder, "Errors.kt"));
-        supportingFiles.add(new SupportingFile("infrastructure/ByteArrayAdapter.kt.mustache", infrastructureFolder, "ByteArrayAdapter.kt"));
-        supportingFiles.add(new SupportingFile("infrastructure/LocalDateAdapter.kt.mustache", infrastructureFolder, "LocalDateAdapter.kt"));
-        supportingFiles.add(new SupportingFile("infrastructure/LocalDateTimeAdapter.kt.mustache", infrastructureFolder, "LocalDateTimeAdapter.kt"));
-        supportingFiles.add(new SupportingFile("infrastructure/UUIDAdapter.kt.mustache", infrastructureFolder, "UUIDAdapter.kt"));
+            if (cm.vars != null) {
+                for (CodegenProperty var : cm.vars) {
+                    var.vendorExtensions.put(VENDOR_EXTENSION_ESCAPED_NAME, escapeIdentifier(var.name));
+                }
+            }
+            if (cm.requiredVars != null) {
+                for (CodegenProperty var : cm.requiredVars) {
+                    var.vendorExtensions.put(VENDOR_EXTENSION_ESCAPED_NAME, escapeIdentifier(var.name));
+                }
+            }
+            if (cm.optionalVars != null) {
+                for (CodegenProperty var : cm.optionalVars) {
+                    var.vendorExtensions.put(VENDOR_EXTENSION_ESCAPED_NAME, escapeIdentifier(var.name));
+                }
+            }
+        }
+        return objs;
+    }
+
+    private static String escapeIdentifier(String identifier) {
+
+        // the kotlin grammar permits a wider set of characters in their identifiers that all target
+        // platforms permit (namely jvm). in order to remain compatible with target platforms, we
+        // initially replace all illegal target characters before escaping the identifier if required.
+        identifier = identifier.replaceAll(IDENTIFIER_REPLACEMENTS, "_");
+        if (IDENTIFIER_PATTERN.matcher(identifier).matches()) return identifier;
+        return '`' + identifier + '`';
+    }
+
+    private static void removeDuplicates(List<CodegenProperty> list) {
+        Set<String> set = new HashSet<>();
+        Iterator<CodegenProperty> iterator = list.iterator();
+        while (iterator.hasNext()) {
+            CodegenProperty item = iterator.next();
+            if (set.contains(item.name)) iterator.remove();
+            else set.add(item.name);
+        }
+    }
+
+    @Override
+    @SuppressWarnings("unchecked")
+    public Map<String, Object> postProcessOperationsWithModels(Map<String, Object> objs, List<Object> allModels) {
+        super.postProcessOperationsWithModels(objs, allModels);
+        Map<String, Object> operations = (Map<String, Object>) objs.get("operations");
+        if (operations != null) {
+            List<CodegenOperation> ops = (List<CodegenOperation>) operations.get("operation");
+            for (CodegenOperation operation : ops) {
+                if (operation.hasConsumes == Boolean.TRUE) {
+                    if (isMultipartType(operation.consumes)) {
+                        operation.isMultipart = Boolean.TRUE;
+                    }
+                }
+            }
+        }
+        return operations;
+    }
+
+    private static boolean isMultipartType(List<Map<String, String>> consumes) {
+        Map<String, String> firstType = consumes.get(0);
+        if (firstType != null) {
+            return "multipart/form-data".equals(firstType.get("mediaType"));
+        }
+        return false;
     }
 }