GitVita
New repositoryImport repositoryNew issue
Your repositories Your dashboard Sign in

openai/openai-java

Public

mirrored from https://github.com/openai/openai-javaAvailable

Watch0Fork0Star0
CodeCommitsIssuesPull requestsActionsInsightsSecurity
v4.24.1

Branches

Tags

  • No tags available.
0Branches0Tags
Go to file
Add file
Code

Clone

HTTPS

Download ZIP

CONTRIBUTING.md

217lines · modeblame

RawDownload
Latest commit unavailable.
067258e8stainless-app[bot]1 years ago1# Contributing to OpenAI Java SDK
2
3## Setting up the environment
4
5This 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
9The 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
24Most of the SDK is generated code. Modifications to code will be persisted between generations, but may
25result in merge conflicts between manual patches and changes from the generator. The generator will never
26modify the contents of the `openai-java-example/` directory.
27
28## Adding and running examples
29
30All 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
34package com.openai.example;
35
36public class YourExample {
37public 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
49If 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
51To 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
60Then 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
65implementation("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
78Alternatively, you can build and install the JAR files directly:
79
80```sh
81$ ./gradlew build
82```
83
84JAR files will be available in each module's `build/libs/` directory.
85
86## Running tests
87
88Most tests require [our mock server](https://github.com/stoplightio/prism) to be running against the OpenAPI spec to work.
89
90The 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
96You can also manually start the mock server if you want to run tests repeatedly:
97
98```sh
99$ ./scripts/mock
100```
101
102Then 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
118The 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
128This repository uses [Spotless](https://github.com/diffplug/spotless) with Palantir Java Format for code formatting and various linting tools.
129
130To check formatting and run lints:
131
132```sh
133$ ./scripts/lint
134```
135
136This will compile all modules and run static analysis checks.
137
138To fix all formatting issues automatically:
139
140```sh
141$ ./scripts/format
142```
143
144You can also check formatting directly with Gradle:
145
146```sh
147$ ./gradlew spotlessCheck # Check formatting
148```
149
150## Building
151
152To build all modules:
153
154```sh
155$ ./gradlew build
156```
157
158To build a specific module:
159
160```sh
161$ ./gradlew :openai-java-core:build
162```
163
164## Adding and running examples
165
166All 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
171package com.openai.example;
172
173public class YourExample {
174public static void main(String[] args) {
175// ...
176}
177}
178```
179
180## Publishing and releases
181
182Changes made to this repository via the automated release PR pipeline should publish to Maven Central automatically. If
183the changes aren't made through the automated pipeline, you may want to make releases manually.
184
185### Publish with a GitHub workflow
186
187You 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
191If you need to manually release a package, you can run:
192
193```sh
194$ ./gradlew publishToSonatype closeAndReleaseSonatypeStagingRepository
195```
196
197This 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
208Some 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```