|
| 1 | +# Contributing to OpenAI Java SDK |
| 2 | + |
| 3 | +## Setting up the environment |
| 4 | + |
| 5 | +This repository uses [Gradle](https://gradle.org/) with Kotlin DSL for building and dependency management. The SDK requires Java 8, but development requires JDK 21 for the Kotlin toolchain. |
| 6 | + |
| 7 | +## Project structure |
| 8 | + |
| 9 | +The SDK consists of three artifacts: |
| 10 | + |
| 11 | +- `openai-java-core` |
| 12 | + - Contains core SDK logic |
| 13 | + - Does not depend on [OkHttp](https://square.github.io/okhttp) |
| 14 | + - Exposes [`OpenAIClient`](openai-java-core/src/main/kotlin/com/openai/client/OpenAIClient.kt), [`OpenAIClientAsync`](openai-java-core/src/main/kotlin/com/openai/client/OpenAIClientAsync.kt), [`OpenAIClientImpl`](openai-java-core/src/main/kotlin/com/openai/client/OpenAIClientImpl.kt), and [`OpenAIClientAsyncImpl`](openai-java-core/src/main/kotlin/com/openai/client/OpenAIClientAsyncImpl.kt), all of which can work with any HTTP client |
| 15 | +- `openai-java-client-okhttp` |
| 16 | + - Depends on [OkHttp](https://square.github.io/okhttp) |
| 17 | + - Exposes [`OpenAIOkHttpClient`](openai-java-client-okhttp/src/main/kotlin/com/openai/client/okhttp/OpenAIOkHttpClient.kt) and [`OpenAIOkHttpClientAsync`](openai-java-client-okhttp/src/main/kotlin/com/openai/client/okhttp/OpenAIOkHttpClientAsync.kt), which provide a way to construct [`OpenAIClientImpl`](openai-java-core/src/main/kotlin/com/openai/client/OpenAIClientImpl.kt) and [`OpenAIClientAsyncImpl`](openai-java-core/src/main/kotlin/com/openai/client/OpenAIClientAsyncImpl.kt), respectively, using OkHttp |
| 18 | +- `openai-java` |
| 19 | + - Depends on and exposes the APIs of both `openai-java-core` and `openai-java-client-okhttp` |
| 20 | + - Does not have its own logic |
| 21 | + |
| 22 | +## Modifying or adding code |
| 23 | + |
| 24 | +Most of the SDK is generated code. Modifications to code will be persisted between generations, but may |
| 25 | +result in merge conflicts between manual patches and changes from the generator. The generator will never |
| 26 | +modify the contents of the `openai-java-example/` directory. |
| 27 | + |
| 28 | +## Adding and running examples |
| 29 | + |
| 30 | +All files in the `openai-java-example/` directory are not modified by the generator and can be freely edited or added to. |
| 31 | + |
| 32 | +```java |
| 33 | +// openai-java-example/src/main/java/com/openai/example/YourExample.java |
| 34 | +package com.openai.example; |
| 35 | + |
| 36 | +public class YourExample { |
| 37 | + public static void main(String[] args) { |
| 38 | + // ... |
| 39 | + } |
| 40 | +} |
| 41 | +``` |
| 42 | + |
| 43 | +```sh |
| 44 | +$ ./gradlew :openai-java-example:run -PmainClass=com.openai.example.YourExample |
| 45 | +``` |
| 46 | + |
| 47 | +## Using the repository from source |
| 48 | + |
| 49 | +If you'd like to use the repository from source, you can either [install from git](https://jitpack.io/) or link to a cloned repository. |
| 50 | + |
| 51 | +To use a local version of this library from source in another project, you can publish it to your local Maven repository: |
| 52 | + |
| 53 | +```sh |
| 54 | +$ ./gradlew publishToMavenLocal |
| 55 | +``` |
| 56 | + |
| 57 | +> [!NOTE] |
| 58 | +> For now, to publish locally, you'll need to comment out the line for `signAllPublications()` here: `buildSrc/src/main/kotlin/openai.publish.gradle.kts` |
| 59 | +
|
| 60 | +Then in your project's `build.gradle.kts` or `pom.xml`, reference the locally published version: |
| 61 | + |
| 62 | +<!-- x-release-please-start-version --> |
| 63 | + |
| 64 | +```kotlin |
| 65 | +implementation("com.openai:openai-java:2.9.1") |
| 66 | +``` |
| 67 | + |
| 68 | +```xml |
| 69 | +<dependency> |
| 70 | + <groupId>com.openai</groupId> |
| 71 | + <artifactId>openai-java</artifactId> |
| 72 | + <version>2.9.1</version> |
| 73 | +</dependency> |
| 74 | +``` |
| 75 | + |
| 76 | +<!-- x-release-please-end --> |
| 77 | + |
| 78 | +Alternatively, you can build and install the JAR files directly: |
| 79 | + |
| 80 | +```sh |
| 81 | +$ ./gradlew build |
| 82 | +``` |
| 83 | + |
| 84 | +JAR files will be available in each module's `build/libs/` directory. |
| 85 | + |
| 86 | +## Running tests |
| 87 | + |
| 88 | +Most tests require [our mock server](https://github.com/stoplightio/prism) to be running against the OpenAPI spec to work. |
| 89 | + |
| 90 | +The test script will automatically start the mock server for you (if it's not already running) and run the tests against it: |
| 91 | + |
| 92 | +```sh |
| 93 | +$ ./scripts/test |
| 94 | +``` |
| 95 | + |
| 96 | +You can also manually start the mock server if you want to run tests repeatedly: |
| 97 | + |
| 98 | +```sh |
| 99 | +$ ./scripts/mock |
| 100 | +``` |
| 101 | + |
| 102 | +Then run the tests: |
| 103 | + |
| 104 | +```sh |
| 105 | +$ ./scripts/test |
| 106 | + |
| 107 | +``` |
| 108 | + |
| 109 | +### Test configuration |
| 110 | + |
| 111 | +- Tests run in parallel for better performance |
| 112 | +- Mock server runs on `localhost:4010` |
| 113 | +- You can disable mock server tests with `SKIP_MOCK_TESTS=true` |
| 114 | +- You can target a custom API URL with `TEST_API_BASE_URL=<url>` |
| 115 | + |
| 116 | +### Testing framework |
| 117 | + |
| 118 | +The project uses: |
| 119 | + |
| 120 | +- **JUnit 5** for test framework |
| 121 | +- **Mockito** for mocking |
| 122 | +- **AssertJ** for fluent assertions |
| 123 | +- **WireMock** for HTTP service mocking |
| 124 | +- **Custom TestServerExtension** for mock server management |
| 125 | + |
| 126 | +## Linting and formatting |
| 127 | + |
| 128 | +This repository uses [Spotless](https://github.com/diffplug/spotless) with Palantir Java Format for code formatting and various linting tools. |
| 129 | + |
| 130 | +To check formatting and run lints: |
| 131 | + |
| 132 | +```sh |
| 133 | +$ ./scripts/lint |
| 134 | +``` |
| 135 | + |
| 136 | +This will compile all modules and run static analysis checks. |
| 137 | + |
| 138 | +To fix all formatting issues automatically: |
| 139 | + |
| 140 | +```sh |
| 141 | +$ ./scripts/format |
| 142 | +``` |
| 143 | + |
| 144 | +You can also check formatting directly with Gradle: |
| 145 | + |
| 146 | +```sh |
| 147 | +$ ./gradlew spotlessCheck # Check formatting |
| 148 | +``` |
| 149 | + |
| 150 | +## Building |
| 151 | + |
| 152 | +To build all modules: |
| 153 | + |
| 154 | +```sh |
| 155 | +$ ./gradlew build |
| 156 | +``` |
| 157 | + |
| 158 | +To build a specific module: |
| 159 | + |
| 160 | +```sh |
| 161 | +$ ./gradlew :openai-java-core:build |
| 162 | +``` |
| 163 | + |
| 164 | +## Adding and running examples |
| 165 | + |
| 166 | +All files in the `openai-java-example/` directory are not modified by the generator and can be freely edited or added to. |
| 167 | + |
| 168 | +```java |
| 169 | +// add an example to openai-java-example/src/main/java/com/openai/example/<YourExample>.java |
| 170 | + |
| 171 | +package com.openai.example; |
| 172 | + |
| 173 | +public class YourExample { |
| 174 | + public static void main(String[] args) { |
| 175 | + // ... |
| 176 | + } |
| 177 | +} |
| 178 | +``` |
| 179 | + |
| 180 | +## Publishing and releases |
| 181 | + |
| 182 | +Changes made to this repository via the automated release PR pipeline should publish to Maven Central automatically. If |
| 183 | +the changes aren't made through the automated pipeline, you may want to make releases manually. |
| 184 | + |
| 185 | +### Publish with a GitHub workflow |
| 186 | + |
| 187 | +You can release to package managers by using [the `Publish Sonatype` GitHub action](https://www.github.com/openai/openai-java/actions/workflows/publish-sonatype.yml). This requires setup organization or repository secrets to be configured. |
| 188 | + |
| 189 | +### Publish manually |
| 190 | + |
| 191 | +If you need to manually release a package, you can run: |
| 192 | + |
| 193 | +```sh |
| 194 | +$ ./gradlew publishToSonatype closeAndReleaseSonatypeStagingRepository |
| 195 | +``` |
| 196 | + |
| 197 | +This requires the following environment variables to be set: |
| 198 | + |
| 199 | +- `SONATYPE_USER` - Your Sonatype Central Portal username |
| 200 | +- `SONATYPE_PASSWORD` - Your Sonatype Central Portal password |
| 201 | +- `GPG_SIGNING_KEY` - Your GPG private key for signing artifacts |
| 202 | +- `GPG_SIGNING_PASSWORD` - Your GPG key passphrase |
| 203 | + |
| 204 | +## Development tools |
| 205 | + |
| 206 | +### Available gradle tasks |
| 207 | + |
| 208 | +Some useful Gradle tasks: |
| 209 | + |
| 210 | +```sh |
| 211 | +$ ./gradlew tasks # List all available tasks |
| 212 | +$ ./gradlew build # Build all modules |
| 213 | +$ ./gradlew test # Run all tests |
| 214 | +$ ./gradlew spotlessApply # Format code |
| 215 | +$ ./gradlew publishToMavenLocal # Publish to local Maven repository |
| 216 | +$ ./gradlew dependencies # Show dependency tree |
| 217 | +``` |
![stainless-app[bot]](https://avatars.githubusercontent.com/in/378072?v=4&size=40){kind=avatar}
0 commit comments