feat:Update OpenAPI spec with new properties, enum values, and schema changes#186
feat:Update OpenAPI spec with new properties, enum values, and schema changes#186
Conversation
WalkthroughThe changes update the OpenAPI specification by removing Java and Kotlin code examples from certain endpoints, introducing new optional properties ( Changes
Poem
✨ Finishing Touches🧪 Generate unit tests
Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out. 🪧 TipsChatThere are 3 ways to chat with CodeRabbit:
SupportNeed help? Create a ticket on our support page for assistance with any issues or questions. Note: Be mindful of the bot's finite context window. It's strongly recommended to break down tasks such as reading entire modules into smaller chunks. For a focused discussion, use review comments to chat about specific files and their changes, instead of using the PR comments. CodeRabbit Commands (Invoked using PR comments)
Other keywords and placeholders
CodeRabbit Configuration File (
|
![github-actions[bot]](https://avatars.githubusercontent.com/in/15368?s=60&v=4){kind=small}
coderabbitai
Bot
changed the title
![coderabbitai[bot]](https://avatars.githubusercontent.com/in/347564?s=60&v=4){kind=small}
There was a problem hiding this comment.
Actionable comments posted: 3
♻️ Duplicate comments (2)
src/libs/tryAGI.OpenAI/openapi.yaml (2)
21101-21109: Same verification needed for.doneevent rename.Run the script above; confirm docs, examples, and tests use the new value exclusively.
21339-21347: Verify allresponse.output_text.annotation.addedreferences updated.Old value
response.output_text_annotation.addedmust be removed throughout the spec & codebase.
🧹 Nitpick comments (1)
src/libs/tryAGI.OpenAI/openapi.yaml (1)
15950-15952: Check naming overlap with existingdescriptionfields.
server_descriptionduplicates the semantic meaning of a plaindescriptionkey already present in many schemas.
Unless you need both a short label and a long description, consider re-usingdescriptionfor consistency and to keep the schema shallow.
📜 Review details
Configuration used: CodeRabbit UI
Review profile: CHILL
Plan: Pro
⛔ Files ignored due to path filters (13)
src/libs/tryAGI.OpenAI/Generated/tryAGI.OpenAI..JsonSerializerContext.g.csis excluded by!**/generated/**src/libs/tryAGI.OpenAI/Generated/tryAGI.OpenAI.Models.InputFileContent.g.csis excluded by!**/generated/**src/libs/tryAGI.OpenAI/Generated/tryAGI.OpenAI.Models.MCPTool.g.csis excluded by!**/generated/**src/libs/tryAGI.OpenAI/Generated/tryAGI.OpenAI.Models.OpenAIFile.g.csis excluded by!**/generated/**src/libs/tryAGI.OpenAI/Generated/tryAGI.OpenAI.Models.OpenAIFilePurpose.g.csis excluded by!**/generated/**src/libs/tryAGI.OpenAI/Generated/tryAGI.OpenAI.Models.RealtimeServerEventConversationItemInputAudioTranscriptionCompleted.g.csis excluded by!**/generated/**src/libs/tryAGI.OpenAI/Generated/tryAGI.OpenAI.Models.ResponseMCPCallArgumentsDeltaEvent.g.csis excluded by!**/generated/**src/libs/tryAGI.OpenAI/Generated/tryAGI.OpenAI.Models.ResponseMCPCallArgumentsDeltaEventType.g.csis excluded by!**/generated/**src/libs/tryAGI.OpenAI/Generated/tryAGI.OpenAI.Models.ResponseMCPCallArgumentsDoneEvent.g.csis excluded by!**/generated/**src/libs/tryAGI.OpenAI/Generated/tryAGI.OpenAI.Models.ResponseMCPCallArgumentsDoneEventType.g.csis excluded by!**/generated/**src/libs/tryAGI.OpenAI/Generated/tryAGI.OpenAI.Models.ResponseOutputTextAnnotationAddedEvent.g.csis excluded by!**/generated/**src/libs/tryAGI.OpenAI/Generated/tryAGI.OpenAI.Models.ResponseOutputTextAnnotationAddedEventType.g.csis excluded by!**/generated/**src/libs/tryAGI.OpenAI/Generated/tryAGI.OpenAI.Models.TranscriptTextUsageDuration.g.csis excluded by!**/generated/**
📒 Files selected for processing (1)
src/libs/tryAGI.OpenAI/openapi.yaml(9 hunks)
⏰ Context from checks skipped due to timeout of 90000ms. You can increase the timeout in your CodeRabbit configuration to a maximum of 15 minutes (900000ms). (1)
- GitHub Check: Test / Build, test and publish
🔇 Additional comments (3)
src/libs/tryAGI.OpenAI/openapi.yaml (3)
21068-21076: Legacy enum strings are purged
I ranrg -n "response\.mcp_call\.arguments_delta|response\.mcp_call\.arguments_done" --type yamlagainstsrc/libs/tryAGI.OpenAI/openapi.yamland found no matches. All stale references have been removed.
16936-16938: Ensure backend validation for the new enum valueuser_dataAdding
"user_data"to the client enum is backward-compatible, but you must verify that the server accepts it. Please confirm that all validation layers recognize the new value for thepurposefield:
- Confirm the OpenAPI schema’s
purposeenum includes"user_data".- Update any backend validation logic (controllers, serializers, middleware) to accept
"user_data".- Check database constraints or enums (if any) allow
"user_data".- Run end-to-end tests (e.g., file uploads, fine-tune jobs) with
purpose: "user_data".- Optionally, update the YAML examples in
openapi.yamlto demonstrate usage of"user_data".
23728-23733: Confirm property rename in OpenAPI spec and update code referencesVerified that in
src/libs/tryAGI.OpenAI/openapi.yaml, theTranscriptTextUsageDurationschema no longer defines adurationfield—it’s been renamed toseconds. No danglingdurationreferences remain in the spec.
Please ensure any client- or server-side code (including generated SDKs or type definitions) expectingTranscriptTextUsageDuration.durationis updated to useseconds.• src/libs/tryAGI.OpenAI/openapi.yaml:
TranscriptTextUsageDuration.properties.seconds(formerlyduration)
• Review all generated clients/servers forTranscriptTextUsageDuration.durationusage
| - item_id | ||
| - content_index | ||
| - transcript | ||
| - usage | ||
| type: object |
There was a problem hiding this comment.
Making usage a required field could break existing clients.
Previous versions emitted this event without usage; marking it required is a breaking change. Confirm that:
- All producers now supply
usage. - Consumers have been updated before release.
If not, keep it optional or release under a new major version.
🤖 Prompt for AI Agents
In src/libs/tryAGI.OpenAI/openapi.yaml around lines 18296 to 18300, the usage
field is marked as required, which may break existing clients that do not
provide this field. Verify that all event producers now include usage and that
all consumers are updated to handle it. If either condition is not met, revert
usage to optional or consider releasing this change in a new major version to
avoid breaking compatibility.
| file_url: | ||
| type: string | ||
| description: The URL of the file to be sent to the model. |
There was a problem hiding this comment.
🛠️ Refactor suggestion
Declare file_url as a URI and document exclusivity with file_id.
file_url represents a remote resource, so OpenAPI best-practice is to add format: uri for basic syntactic validation.
Also, consider specifying that either file_id or file_url must be supplied (but not both) to avoid ambiguous requests.
file_url:
type: string
+ format: uri
description: The URL of the file to be sent to the model.If mutual exclusivity is desired, add a oneOf/anyOf constraint at the parent schema level.
Committable suggestion skipped: line range outside the PR's diff.
🤖 Prompt for AI Agents
In src/libs/tryAGI.OpenAI/openapi.yaml around lines 14903 to 14905, update the
schema to declare the `file_url` property with `format: uri` to ensure it is
validated as a URI. Additionally, modify the parent schema to enforce mutual
exclusivity between `file_id` and `file_url` by adding a `oneOf` or `anyOf`
constraint, specifying that only one of these fields can be provided in a
request to prevent ambiguity.
| usage: | ||
| type: object | ||
| oneOf: | ||
| - $ref: '#/components/schemas/TranscriptTextUsageTokens' | ||
| - $ref: '#/components/schemas/TranscriptTextUsageDuration' | ||
| description: Usage statistics for the transcription. | ||
| description: "This event is the output of audio transcription for user audio written to the\nuser audio buffer. Transcription begins when the input audio buffer is\ncommitted by the client or server (in `server_vad` mode). Transcription runs\nasynchronously with Response creation, so this event may come before or after\nthe Response events.\n\nRealtime API models accept audio natively, and thus input transcription is a\nseparate process run on a separate ASR (Automatic Speech Recognition) model.\nThe transcript may diverge somewhat from the model's interpretation, and\nshould be treated as a rough guide.\n" | ||
| x-oaiMeta: | ||
| example: "{\n \"event_id\": \"event_2122\",\n \"type\": \"conversation.item.input_audio_transcription.completed\",\n \"item_id\": \"msg_003\",\n \"content_index\": 0,\n \"transcript\": \"Hello, how are you?\"\n}\n" | ||
| example: "{\n \"event_id\": \"event_2122\",\n \"type\": \"conversation.item.input_audio_transcription.completed\",\n \"item_id\": \"msg_003\",\n \"content_index\": 0,\n \"transcript\": \"Hello, how are you?\",\n \"usage\": {\n \"type\": \"tokens\",\n \"total_tokens\": 48,\n \"input_tokens\": 38,\n \"input_token_details\": {\n \"text_tokens\": 10,\n \"audio_tokens\": 28,\n },\n \"output_tokens\": 10,\n }\n}\n" |
There was a problem hiding this comment.
🛠️ Refactor suggestion
Consider a discriminator for the oneOf usage object.
oneOf with TranscriptTextUsageTokens and TranscriptTextUsageDuration relies on structural uniqueness.
Add a discriminator (e.g., the existing type property) for unambiguous deserialisation across languages.
usage:
type: object
oneOf:
- $ref: '#/components/schemas/TranscriptTextUsageTokens'
- $ref: '#/components/schemas/TranscriptTextUsageDuration'
+ discriminator:
+ propertyName: type
description: Usage statistics for the transcription.Committable suggestion skipped: line range outside the PR's diff.
🤖 Prompt for AI Agents
In src/libs/tryAGI.OpenAI/openapi.yaml around lines 18326 to 18334, the oneOf
schema using TranscriptTextUsageTokens and TranscriptTextUsageDuration lacks a
discriminator, which can cause ambiguous deserialization. Add a discriminator
property, such as the existing 'type' field, to the oneOf definition to clearly
distinguish between these object types during deserialization across different
languages.
1 participant
Summary by CodeRabbit
New Features
Improvements
Other Changes