https://github.com/swooby/openai-openapi-kotlin
OpenAI OpenAPI Specification - Kotlin
https://github.com/swooby/openai-openapi-kotlin
kotlin kotlin-android openai openai-api openai-realtime openai-realtime-api openapi
Last synced: 3 months ago
JSON representation
OpenAI OpenAPI Specification - Kotlin
- Host: GitHub
- URL: https://github.com/swooby/openai-openapi-kotlin
- Owner: swooby
- Created: 2025-01-17T15:41:01.000Z (5 months ago)
- Default Branch: main
- Last Pushed: 2025-02-23T11:55:51.000Z (3 months ago)
- Last Synced: 2025-02-23T12:27:51.991Z (3 months ago)
- Topics: kotlin, kotlin-android, openai, openai-api, openai-realtime, openai-realtime-api, openapi
- Language: Kotlin
- Homepage:
- Size: 722 KB
- Stars: 0
- Watchers: 1
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
Awesome Lists containing this project
README
# openai-openapi-kotlin
**OpenAI OpenAPI Specification - Kotlin**
From https://github.com/openai/openai-openapi/blob/master/openapi.yaml
NOTES:
* There is https://github.com/openai/openai-java, which OpenAI describes as
"The official Java library for the OpenAI API", but:
1. That "official" library lags behind https://github.com/openai/openai-openapi/blob/master/openapi.yaml
For example, as of 2025/02/12 is is **STILL** lacking OpenAI's Realtime API (https://platform.openai.com/docs/api-reference/realtime), which is my main use case.
2. `openai-java` is actually a nearly fully modernized Kotlin library, so the name
`openai-java` is legacy;
it really should be named `openai-kotlin`.
* I was initially tempted to inflate this repo to contain multiple openapi-generator
generated languages, but for now I am limiting it to Kotlin.
* openapi-generator has >4k open Issues:
https://github.com/OpenAPITools/openapi-generator/issues
So, no promises about the quality of its output.
Maybe one day I will open a PR to auto-generate some of the changes I made manually.
Requirements:
* OpenAPI Generator: https://openapi-generator.tech/docs/installation
Optional:
1. `curl -o openapi-YYYYMMDD.yaml https://raw.githubusercontent.com/openai/openai-openapi/refs/heads/master/openapi.yaml`
You don't have to do this.
`openapi-generator` supports fetching the specification directly from a url.
I prefer to save a snapshot of the specification that was used for the generation.
## Generate Whole OpenAI API
1. `time openapi-generator generate -i openapi-YYYYMMDD.yaml -g kotlin -o ./lib --skip-validate-spec --additional-properties=artifactId=openai-kotlin-client,artifactVersion=0.0.1,groupId=com.openai,packageName=com.openai`
(< 5 seconds on MacBook Pro M4 Pro)
2. `cp lib/build.gradle .`
3. `mv lib/gradle* lib/settings.gradle .`
4. `echo -e "\ninclude(\":lib\")" >> settings.gradle`
5. Edit `build.gradle` to be a project file and `lib/build.gradle` to be a module file.
6. `chmod +x ./gradlew`
7. `./gradlew build`
(< 20 seconds on MacBook Pro M4 Pro to [eventually; see "Changes"] successfully compile from clean)
All of this is also shown in the `openai-kotlin-client.sh` file.
## Changes
At this point, the build will actually fail.
I had to make some manual changes in order to get it to compile successfully:
1. AudioApi.kt:
1. change `AudioResponseFormat? = json` to `AudioResponseFormat? = AudioResponseFormat.json`
2. change `timestampGranularities?.value` to `timestampGranularities`
2. remove `data` (`data class ...`->`class ...`) in:
1. CreateAssistantRequestToolResourcesFileSearch.kt
2. CreateThreadRequestToolResourcesFileSearch.kt
This just got it to **COMPILE** successfully!
I had to make further changes in order to get it to **RUN** successfully.
All of my changes can be seen at:
https://github.com/swooby/openai-openapi-kotlin/pull/1/files
## Updates
When a new spec comes out:
1. Make sure to start from a fresh/stashed checkout.
2. `curl -o openapi-YYYYMMDD.yaml https://raw.githubusercontent.com/openai/openai-openapi/refs/heads/master/openapi.yaml`
3. `openapi-generator generate -i openapi-YYYYMMDD.yaml -g kotlin -o ./lib --skip-validate-spec --additional-properties=artifactId=openai-kotlin-client,artifactVersion=0.0.1,groupId=com.openai,packageName=com.openai`
4. optimize imports of `models`; NOTE: This will fail on any file that has a compiler error!
5. `mv lib/build.gradle lib/build.gradle.kts`
6. `rm -f ./gradle && mv lib/gradle* .`
7. `mv lib/settings.gradle ./settings.gradle.kts`
8. Review each changed file, especially ones that show as modified in:
https://github.com/swooby/openai-openapi-kotlin/pull/1/files
1. First review with the settings.gradle and build.gradle files.
1. `gradle*`: probably discard all changes
2. `settings.gradle.kts`: probably discard all changes
3. `lib/build.gradle.kts`: probably discard all changes
4. While you are here, update any dependencies in `gradle/libs.versions.toml`
2. `docs`: probably keep all changes
3. `test`: probably keep all changes except...
1. probably delete `RealtimeResponseCreateParamsMaxResponseOutputTokensTest`
2. probably delete `RealtimeResponseMaxOutputTokensTest`
4. `infrastructure`:
1. `AudioApi.kt`: probably discard all changes
2. `ApiClient.kt`: probably discard all changes
3. `BigDecimalAdapter.kt`: probably discard all changes
4. `BigIntegerAdapter.kt`: probably discard all changes
5. `Serializer.kt`: probably discard all changes
5. `models`:
1. `CreateAssistantRequestToolResourcesFileSearch`: keep non-data class (syntax error for data class to have no constructor parameters)
2. `CreateThreadRequestToolResourcesFileSearch`: keep non-data class (syntax error for data class to have no constructor parameters)
3. `Realtime*` files:
(This can get a little complicated...)
1. `RealtimeClientEvent*`: Keep all `type: RealtimeClientEvent*.Type = RealtimeClientEvent*.Type....` one-line assignments
2. `RealtimeConversationItem`
1. add/keep `in_progress` to nested `Status`; undocumented value comes from the server
3. `RealtimeConversationItemContentInner`
1. add/keep `audio` to nested `Type`; undocumented value comes from the server
4. `RealtimeResponse`
1. change `maxOutputTokens` to type `RealtimeSessionMaxResponseOutputTokens`
2. add/keep `in_progress` to nested `Status`; undocumented value comes from the server
5. `RealtimeResponseCreateParams`
1. change `maxResponseOutputTokens` to type `RealtimeSessionMaxResponseOutputTokens`
6. `RealtimeResponseCreateParamsConversation`
1. add/keep `enum class ... auto, none ...`
7. move `RealtimeResponseCreateParamsMaxResponseOutputTokens` to common `RealtimeSessionMaxResponseOutputTokens`
8. move `RealtimeResponseMaxOutputTokens` to common `RealtimeSessionMaxResponseOutputTokens`
9. `RealtimeServerEventConversationItemCreated`
1. add/keep nullable `previousItemId`
10. `RealtimeServerEventInputAudioBufferCommitted`:
1. add/keep nullable `previousItemId`
11. `RealtimeSession`
1. add/keep `@SerializeNull` REALLY?!?!?!?
2. change `maxResponseOutputTokens` to type `RealtimeSessionMaxResponseOutputTokens`
12. `RealtimeSessionCreateRequest`
1. add/keep `@SerializeNull`
2. change `maxResponseOutputTokens` to type `RealtimeSessionMaxResponseOutputTokens`
13. `RealtimeSessionCreateRequestInputAudioTranscription`
1. add/keep nested `enum class Model whisper-1 ...`
2. change `model` to nested `Model`
14. `RealtimeSessionCreateRequestTurnDetection`
1. add/keep nested `enum class Type server_vad ...`
2. change `type` to nested `Type`
15. `RealtimeSessionCreateResponse`
1. change `maxResponseOutputTokens` to type `RealtimeSessionMaxResponseOutputTokens`