An OpenAPI Generator Plus template for a Kotlin API client using Ktor
npm install @openapi-generator-plus/kotlin-client-generatorThis generator uses Kotlin Serialization, Ktor and OkHttp.
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
, 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.$3
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 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
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
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
$3
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
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
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
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}"))