release: 0.28.0

.release-please-manifest.json

@@ -1,3 +1,3 @@
 {
-  ".": "0.27.0"
+  ".": "0.28.0"
 }

CHANGELOG.md

@@ -1,5 +1,18 @@
 # Changelog
 
+## 0.28.0 (2025-02-24)
+
+Full Changelog: [v0.27.0...v0.28.0](https://github.com/openai/openai-java/compare/v0.27.0...v0.28.0)
+
+### Features
+
+* **api:** add latest stable/preview version helper methods ([#226](https://github.com/openai/openai-java/issues/226)) ([9766b7c](https://github.com/openai/openai-java/commit/9766b7c93928c9837fa13cbab5969a883ccec22a))
+
+
+### Documentation
+
+* add source file links to readme ([#247](https://github.com/openai/openai-java/issues/247)) ([d9b67d7](https://github.com/openai/openai-java/commit/d9b67d7ef7552112774039acf951a582c3eeefea))
+
 ## 0.27.0 (2025-02-24)
 
 Full Changelog: [v0.26.1...v0.27.0](https://github.com/openai/openai-java/compare/v0.26.1...v0.27.0)

README.md

@@ -9,8 +9,8 @@
 
 <!-- x-release-please-start-version -->
 
-[![Maven Central](https://img.shields.io/maven-central/v/com.openai/openai-java)](https://central.sonatype.com/artifact/com.openai/openai-java/0.27.0)
-[![javadoc](https://javadoc.io/badge2/com.openai/openai-java/0.27.0/javadoc.svg)](https://javadoc.io/doc/com.openai/openai-java/0.27.0)
+[![Maven Central](https://img.shields.io/maven-central/v/com.openai/openai-java)](https://central.sonatype.com/artifact/com.openai/openai-java/0.28.0)
+[![javadoc](https://javadoc.io/badge2/com.openai/openai-java/0.28.0/javadoc.svg)](https://javadoc.io/doc/com.openai/openai-java/0.28.0)
 
 <!-- x-release-please-end -->
 
@@ -25,7 +25,7 @@ The REST API documentation can be found on [platform.openai.com](https://platfor
 ### Gradle
 
 ```kotlin
-implementation("com.openai:openai-java:0.27.0")
+implementation("com.openai:openai-java:0.28.0")
 ```
 
 ### Maven
@@ -34,7 +34,7 @@ implementation("com.openai:openai-java:0.27.0")
 <dependency>
     <groupId>com.openai</groupId>
     <artifactId>openai-java</artifactId>
-    <version>0.27.0</version>
+    <version>0.28.0</version>
 </dependency>
 ```
 
@@ -177,7 +177,7 @@ The SDK defines methods that return response "chunk" streams, where each chunk c
 
 Some of these methods may have streaming and non-streaming variants, but a streaming method will always have a `Streaming` suffix in its name, even if it doesn't have a non-streaming variant.
 
-These streaming methods return `StreamResponse` for synchronous clients:
+These streaming methods return [`StreamResponse`](openai-java-core/src/main/kotlin/com/openai/core/http/StreamResponse.kt) for synchronous clients:
 
 ```java
 import com.openai.core.http.StreamResponse;
@@ -191,7 +191,7 @@ try (StreamResponse<ChatCompletionChunk> streamResponse = client.chat().completi
 }
 ```
 
-Or `AsyncStreamResponse` for asynchronous clients:
+Or [`AsyncStreamResponse`](openai-java-core/src/main/kotlin/com/openai/core/http/AsyncStreamResponse.kt) for asynchronous clients:
 
 ```java
 import com.openai.core.http.AsyncStreamResponse;
@@ -236,7 +236,7 @@ client.async().chat().completions().createStreaming(params)
     });
 ```
 
-Async streaming uses a dedicated per-client cached thread pool `Executor` to stream without blocking the current thread. This default is suitable for most purposes.
+Async streaming uses a dedicated per-client cached thread pool [`Executor`](https://docs.oracle.com/javase/8/docs/api/java/util/concurrent/Executor.html) to stream without blocking the current thread. This default is suitable for most purposes.
 
 To use a different `Executor`, configure the subscription using the `executor` parameter:
 
@@ -267,7 +267,7 @@ OpenAIClient client = OpenAIOkHttpClient.builder()
 
 The SDK defines methods that return binary responses, which are used for API responses that shouldn't necessarily be parsed, like non-JSON data.
 
-These methods return `HttpResponse`:
+These methods return [`HttpResponse`](openai-java-core/src/main/kotlin/com/openai/core/http/HttpResponse.kt):
 
 ```java
 import com.openai.core.http.HttpResponse;
@@ -279,7 +279,7 @@ FileContentParams params = FileContentParams.builder()
 HttpResponse response = client.files().content(params);
 ```
 
-To save the response content to a file, use the `Files.copy(...)` method:
+To save the response content to a file, use the [`Files.copy(...)`](https://docs.oracle.com/javase/8/docs/api/java/nio/file/Files.html#copy-java.io.InputStream-java.nio.file.Path-java.nio.file.CopyOption...-) method:
 
 ```java
 import com.openai.core.http.HttpResponse;
@@ -299,7 +299,7 @@ try (HttpResponse response = client.files().content(params)) {
 }
 ```
 
-Or transfer the response content to any `OutputStream`:
+Or transfer the response content to any [`OutputStream`](https://docs.oracle.com/javase/8/docs/api/java/io/OutputStream.html):
 
 ```java
 import com.openai.core.http.HttpResponse;
@@ -318,7 +318,7 @@ try (HttpResponse response = client.files().content(params)) {
 
 The SDK throws custom unchecked exception types:
 
-- `OpenAIServiceException`: Base class for HTTP errors. See this table for which exception subclass is thrown for each HTTP status code:
+- [`OpenAIServiceException`](openai-java-core/src/main/kotlin/com/openai/errors/OpenAIServiceException.kt): Base class for HTTP errors. See this table for which exception subclass is thrown for each HTTP status code:
 
   | Status | Exception                       |
   | ------ | ------------------------------- |
@@ -331,11 +331,11 @@ The SDK throws custom unchecked exception types:
   | 5xx    | `InternalServerException`       |
   | others | `UnexpectedStatusCodeException` |
 
-- `OpenAIIoException`: I/O networking errors.
+- [`OpenAIIoException`](openai-java-core/src/main/kotlin/com/openai/errors/OpenAIIoException.kt): I/O networking errors.
 
-- `OpenAIInvalidDataException`: Failure to interpret successfully parsed data. For example, when accessing a property that's supposed to be required, but the API unexpectedly omitted it from the response.
+- [`OpenAIInvalidDataException`](openai-java-core/src/main/kotlin/com/openai/errors/OpenAIInvalidDataException.kt): Failure to interpret successfully parsed data. For example, when accessing a property that's supposed to be required, but the API unexpectedly omitted it from the response.
 
-- `OpenAIException`: Base class for all exceptions. Most errors will result in one of the previously mentioned ones, but completely generic errors may be thrown using the base class.
+- [`OpenAIException`](openai-java-core/src/main/kotlin/com/openai/errors/OpenAIException.kt): Base class for all exceptions. Most errors will result in one of the previously mentioned ones, but completely generic errors may be thrown using the base class.
 
 ## Pagination
 
@@ -520,7 +520,7 @@ ChatCompletionCreateParams params = ChatCompletionCreateParams.builder()
 
 These can be accessed on the built object later using the `_additionalHeaders()`, `_additionalQueryParams()`, and `_additionalBodyProperties()` methods. You can also set undocumented parameters on nested headers, query params, or body classes using the `putAdditionalProperty` method. These properties can be accessed on the built object later using the `_additionalProperties()` method.
 
-To set a documented parameter or property to an undocumented or not yet supported _value_, pass a `JsonValue` object to its setter:
+To set a documented parameter or property to an undocumented or not yet supported _value_, pass a [`JsonValue`](openai-java-core/src/main/kotlin/com/openai/core/JsonValue.kt) object to its setter:
 
 ```java
 import com.openai.core.JsonValue;
@@ -591,7 +591,7 @@ if (messages.isMissing()) {
 
 In rare cases, the API may return a response that doesn't match the expected type. For example, the SDK may expect a property to contain a `String`, but the API could return something else.
 
-By default, the SDK will not throw an exception in this case. It will throw `OpenAIInvalidDataException` only if you directly access the property.
+By default, the SDK will not throw an exception in this case. It will throw [`OpenAIInvalidDataException`](openai-java-core/src/main/kotlin/com/openai/errors/OpenAIInvalidDataException.kt) only if you directly access the property.
 
 If you would prefer to check that the response is completely well-typed upfront, then either call `validate()`:
 

build.gradle.kts

@@ -8,7 +8,7 @@ repositories {
 
 allprojects {
     group = "com.openai"
-    version = "0.27.0" // x-release-please-version
+    version = "0.28.0" // x-release-please-version
 }
 
 subprojects {

openai-java-core/src/main/kotlin/com/openai/azure/AzureOpenAIServiceVersion.kt

@@ -8,6 +8,18 @@ class AzureOpenAIServiceVersion private constructor(@get:JvmName("value") val va
         private val values: ConcurrentHashMap<String, AzureOpenAIServiceVersion> =
             ConcurrentHashMap()
 
+        @JvmStatic
+        fun latestStableVersion(): AzureOpenAIServiceVersion {
+            // We can update the value every general available(GA)/stable announcement.
+            return V2024_10_21
+        }
+
+        @JvmStatic
+        fun latestPreviewVersion(): AzureOpenAIServiceVersion {
+            // We can update the value every preview announcement.
+            return V2025_01_01_PREVIEW
+        }
+
         @JvmStatic
         fun fromString(version: String): AzureOpenAIServiceVersion =
             values.computeIfAbsent(version) { AzureOpenAIServiceVersion(version) }

openai-java-core/src/main/kotlin/com/openai/core/ClientOptions.kt

@@ -4,7 +4,6 @@ package com.openai.core
 
 import com.fasterxml.jackson.databind.json.JsonMapper
 import com.openai.azure.AzureOpenAIServiceVersion
-import com.openai.azure.AzureOpenAIServiceVersion.Companion.V2024_10_21
 import com.openai.azure.credential.AzureApiKeyCredential
 import com.openai.core.http.Headers
 import com.openai.core.http.HttpClient
@@ -261,8 +260,10 @@ private constructor(
             if (isAzureEndpoint(baseUrl)) {
                 // Default Azure OpenAI version is used if Azure user doesn't
                 // specific a service API version in 'queryParams'.
-                // We can update the default value every major announcement if needed.
-                replaceQueryParams("api-version", (azureServiceVersion ?: V2024_10_21).value)
+                replaceQueryParams(
+                    "api-version",
+                    (azureServiceVersion ?: AzureOpenAIServiceVersion.latestStableVersion()).value,
+                )
             }
 
             headers.replaceAll(this.headers.build())