OpenAPI Generator Plus Kotlin Client Generator

This generator uses Kotlin Serialization, Ktor and OkHttp.

Development

To use this library in development we use the link command.

Get started by ensuring that your target project is using the same node version so that the global link will be discoverable. We use a .nvmrc file in this project to set the version.

First check that this project builds

pnpm install
pnpm run build

Then to register this directory with the global registry

pnpm run link

Then in your target project run

pnpm link --global @openapi-generator-plus/kotlin-client-generator

Limitations

• This library uses Ktor with OkHttp engine for making network calls. Thus, it follows the current compatibility of OkHttp engines in Ktor, which are JVM and Android.
• This library assumes JSON is used for model representation during network calls.
• This library has a limitation in only supporting one-of discriminators of type string or an enum that is represented in string.
• The generated model objects are not java.io.Serializable, because Kotlin date and time classes are not java.io.Serializable. If you want to put model objects into an android.os.Bundle or android.os.Intent, you need to serialize the model object first (such as to json).

Requirements

• The library was developed with the latest version of Kotlin at the time of development (version 1.9.22), and so it utilises Kotlin language features that were introduced after version 1.9.0, such as data object. Therefore, it’s strongly recommended to use the latest version of Kotlin, if not, at least 1.9.22.
• Gradle version catalog is necessary for the generated build.gradle.kts to reference necessary versions. Ensure you have this in your project before including the API module to the project.

Implementation

There are two approaches you can take when implementing the generated API into an existing project.

1. File browser approach

1. Copy the folder containing the generated API files into the project root directory.
   • The folder generated by the API should contain src/ folder and build.gradle.kts.
   • The folder may be appropriately renamed, e.g. api/, but in this guide, we’ll reference it in the code blocks as {api_folder}.
2. At the root directory of the project, open settings.gradle.kts and add the api directory in the include(...) line along with all the other modules of the project.
   • If this is a plain, standard Android app, it should look something like include(":app", ":{api_folder}")
3. Inside gradle/ directory, create a version catalog if the project does not have it already. Conventionally, it should be named libs.versions.toml.
4. Add the required versions, libraries, and plugins inside the version catalog. Following code block contains the essential set of versions, libraries, and plugins, as specified in the auto-generated build.gradle.kts file.

[versions]
kotlin = "{latest_version that is >= 1.9.22}"
kotlinx-datetime = "{latest_version that is >= 0.5.0}"
kotlinx-serialization = "{latest_version that is >= 1.6.2}"
ktor = "{latest_version that is >= 2.3.7}"

[libraries]
kotlinx-datetime = { module = "org.jetbrains.kotlinx:kotlinx-datetime", version.ref = "kotlinx-datetime" }
kotlinx-serialization-json = { module = "org.jetbrains.kotlinx:kotlinx-serialization-json", version.ref = "kotlinx-serialization" }
ktor-client-content-negotiation = { module = "io.ktor:ktor-client-content-negotiation", version.ref = "ktor" }
ktor-client-core = { module = "io.ktor:ktor-client-core", version.ref = "ktor" }
ktor-client-okhttp = { module = "io.ktor:ktor-client-okhttp", version.ref = "ktor" }
ktor-serialization-kotlinx-json = { module = "io.ktor:ktor-serialization-kotlinx-json", version.ref = "ktor" }

[plugins]
kotlin-jvm = { id = "org.jetbrains.kotlin.jvm", version.ref = "kotlin" }
kotlin-serialization = { id = "org.jetbrains.kotlin.plugin.serialization", version.ref = "kotlin" }

5. Go to build.gradle.kts in the root directory, and append aliases to the two plugins required by the API module, as specified in the version catalog.

plugins {
    … existing list of plugins …

    /** Needed for :api library. */
    alias(libs.plugins.kotlin.jvm) apply false
    alias(libs.plugins.kotlin.serialization) apply false
}

6. [Optional] At this point, you may also go ahead and refactor version managements for all libraries and plugins into libs.versions.toml so that it’s consistent throughout the codebase.

7. Go to build.gradle.kts for the module that uses the generated API, and add the generated API module as a project dependency by appending the following line in the dependencies {…} closure.

implementation(project(":{api_folder}"))

8. Open command prompt in the project root directory and run the following command to build the project to see if all the configurations were done correctly. The build should succeed if every configuration was made correctly.

./gradlew build

2. Android Studio approach

1. Set up version catalog in your project if you haven't done so.

2. Add libraries and plugins required by the generated API module.

[versions]
kotlin = "{latest_version that is >= 1.9.22}"
kotlinx-datetime = "{latest_version that is >= 0.5.0}"
kotlinx-serialization = "{latest_version that is >= 1.6.2}"
ktor = "{latest_version that is >= 2.3.7}"

[libraries]
kotlinx-datetime = { module = "org.jetbrains.kotlinx:kotlinx-datetime", version.ref = "kotlinx-datetime" }
kotlinx-serialization-json = { module = "org.jetbrains.kotlinx:kotlinx-serialization-json", version.ref = "kotlinx-serialization" }
ktor-client-content-negotiation = { module = "io.ktor:ktor-client-content-negotiation", version.ref = "ktor" }
ktor-client-core = { module = "io.ktor:ktor-client-core", version.ref = "ktor" }
ktor-client-okhttp = { module = "io.ktor:ktor-client-okhttp", version.ref = "ktor" }
ktor-serialization-kotlinx-json = { module = "io.ktor:ktor-serialization-kotlinx-json", version.ref = "ktor" }

[plugins]
kotlin-jvm = { id = "org.jetbrains.kotlin.jvm", version.ref = "kotlin" }
kotlin-serialization = { id = "org.jetbrains.kotlin.plugin.serialization", version.ref = "kotlin" }

3. Go to build.gradle.kts in the root directory, and append aliases to the two plugins required by the API module, as specified in the version catalog.

plugins {
  …remaining plugins…

  /** Needed for :api library. */
  alias(libs.plugins.kotlin.jvm) apply false
  alias(libs.plugins.kotlin.serialization) apply false
}

4. Click [File -> New -> Import Module…] from the menu bar and specify the source directory to the generated API.

5. [Optional] Android Studio may have created settings.gradle to include the new module instead of utilising the existing settings.gradle.kts. In that case, remove settings.gradle, and manually append the newly-included module in settings.gradle.kts. e.g...

include(":app", ":api")

6. Go to build.gradle.kts for the module that uses the generated API, and add the generated API module as a project dependency by appending the following line in the dependencies {…} closure.

implementation(project(":{api_folder}"))