npm package: @openapi-generator-plus/kotlin-client-generator
Description: An OpenAPI Generator Plus template for a Kotlin API client using Ktor
Author: Karl von Randow, Hyung Park
Latest version: 0.2.2

# OpenAPI Generator Plus Kotlin Client Generator

This generator uses [Kotlin Serialization](https://kotlinlang.org/docs/serialization.html), 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}"))
```