feat:Deprecate two parameters and operations in Cohere openapi.yaml #271
Conversation
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
WalkthroughAdded deprecation flags in src/libs/Cohere/openapi.yaml: marked two parameters as deprecated and set deprecated: true on multiple operations across the spec, notably around sections following 504 GatewayTimeout/ServiceUnavailable references. Changes
Sequence Diagram(s)Estimated code review effort🎯 2 (Simple) | ⏱️ ~10 minutes Possibly related PRs
Poem
Pre-merge checks and finishing touches❌ Failed checks (1 warning)
✅ Passed checks (2 passed)
✨ 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. Comment |
![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: 1
🧹 Nitpick comments (10)
src/libs/Cohere/openapi.yaml (10)
63-69: Clarify deprecation intent and add sunset metadataGood to mark this property deprecated. Add explicit rationale/timeline so SDKs/docs can surface it, and verify the
deprecatedflag is applied at the correct object level (Schema vs Parameter).Apply a lightweight extension for visibility:
description: "Accepts {\"id\": \"web-search\"}, and/or the \"id\" for a custom connector...\nCompatible Deployments: Cohere Platform\n" deprecated: true + x-deprecation-reason: "Replaced by a newer field/flow. Please migrate." + x-sunset-date: "YYYY-MM-DD" x-fern-audiences:
168-174: Deprecate with guidance; confirm replacement pathFlagging
search_queries_onlyas deprecated is fine. Provide the migration path and sunset to prevent consumer confusion.Suggested additions:
description: "Defaults to `false`... Compatible Deployments: Cohere Platform, Azure, AWS Sagemaker/Bedrock, Private Deployments\n" deprecated: true + x-deprecation-reason: "Superseded by a more granular request option." + x-sunset-date: "YYYY-MM-DD" x-fern-audiences:
1004-1010: Operation-level deprecation: include reason/sunset and check SDK regenerationMarking the operation deprecated is valid. Add reason/sunset so generators and docs surface timelines; ensure regenerating SDKs preserves operationId and adds @deprecated.
'504': $ref: '#/components/responses/GatewayTimeout' deprecated: true + x-deprecation-reason: "Endpoint will be removed; use the replacement route." + x-sunset-date: "YYYY-MM-DD" x-fern-audiences:
1128-1134: Add deprecation metadata (reason/sunset) here as well'504': $ref: '#/components/responses/GatewayTimeout' deprecated: true + x-deprecation-reason: "See migration guide for the new operation." + x-sunset-date: "YYYY-MM-DD" x-fern-audiences:
1198-1204: Consistent deprecation annotations across operations'504': $ref: '#/components/responses/GatewayTimeout' deprecated: true + x-deprecation-reason: "Planned removal." + x-sunset-date: "YYYY-MM-DD" x-fern-audiences:
1271-1277: Surface migration details in spec'504': $ref: '#/components/responses/GatewayTimeout' deprecated: true + x-deprecation-reason: "Superseded by updated API surface." + x-sunset-date: "YYYY-MM-DD" x-fern-audiences:
1343-1349: Deprecation metadata missing'504': $ref: '#/components/responses/GatewayTimeout' deprecated: true + x-deprecation-reason: "Consolidated into a different endpoint." + x-sunset-date: "YYYY-MM-DD" x-fern-audiences:
1421-1427: Same treatment: add reason/sunset for docs and SDKs'504': $ref: '#/components/responses/GatewayTimeout' deprecated: true + x-deprecation-reason: "Deprecated in favor of new flow." + x-sunset-date: "YYYY-MM-DD" x-fern-audiences:
1501-1507: Include migration hints'504': $ref: '#/components/responses/GatewayTimeout' deprecated: true + x-deprecation-reason: "Use the recommended replacement." + x-sunset-date: "YYYY-MM-DD" x-fern-audiences:
6623-6629: Late-spec section: ensure no unintended mass deprecationDouble-check this block wasn’t added by a bulk edit to the wrong operation. Add reason/sunset if intentional.
'504': $ref: '#/components/responses/GatewayTimeout' deprecated: true + x-deprecation-reason: "Intentional deprecation." + x-sunset-date: "YYYY-MM-DD" x-fern-audiences:
📜 Review details
Configuration used: CodeRabbit UI
Review profile: CHILL
Plan: Pro
⛔ Files ignored due to path filters (21)
src/libs/Cohere/Generated/Cohere.CohereClient.Chat.g.csis excluded by!**/generated/**src/libs/Cohere/Generated/Cohere.CohereClient.Classify.g.csis excluded by!**/generated/**src/libs/Cohere/Generated/Cohere.CohereClient.Generate.g.csis excluded by!**/generated/**src/libs/Cohere/Generated/Cohere.CohereClient.Summarize.g.csis excluded by!**/generated/**src/libs/Cohere/Generated/Cohere.ConnectorsClient.CreateConnector.g.csis excluded by!**/generated/**src/libs/Cohere/Generated/Cohere.ConnectorsClient.DeleteConnector.g.csis excluded by!**/generated/**src/libs/Cohere/Generated/Cohere.ConnectorsClient.GetConnector.g.csis excluded by!**/generated/**src/libs/Cohere/Generated/Cohere.ConnectorsClient.ListConnectors.g.csis excluded by!**/generated/**src/libs/Cohere/Generated/Cohere.ConnectorsClient.OAuthAuthorizeConnector.g.csis excluded by!**/generated/**src/libs/Cohere/Generated/Cohere.ConnectorsClient.UpdateConnector.g.csis excluded by!**/generated/**src/libs/Cohere/Generated/Cohere.ICohereClient.Chat.g.csis excluded by!**/generated/**src/libs/Cohere/Generated/Cohere.ICohereClient.Classify.g.csis excluded by!**/generated/**src/libs/Cohere/Generated/Cohere.ICohereClient.Generate.g.csis excluded by!**/generated/**src/libs/Cohere/Generated/Cohere.ICohereClient.Summarize.g.csis excluded by!**/generated/**src/libs/Cohere/Generated/Cohere.IConnectorsClient.CreateConnector.g.csis excluded by!**/generated/**src/libs/Cohere/Generated/Cohere.IConnectorsClient.DeleteConnector.g.csis excluded by!**/generated/**src/libs/Cohere/Generated/Cohere.IConnectorsClient.GetConnector.g.csis excluded by!**/generated/**src/libs/Cohere/Generated/Cohere.IConnectorsClient.ListConnectors.g.csis excluded by!**/generated/**src/libs/Cohere/Generated/Cohere.IConnectorsClient.OAuthAuthorizeConnector.g.csis excluded by!**/generated/**src/libs/Cohere/Generated/Cohere.IConnectorsClient.UpdateConnector.g.csis excluded by!**/generated/**src/libs/Cohere/Generated/Cohere.Models.ChatRequest.g.csis excluded by!**/generated/**
📒 Files selected for processing (1)
src/libs/Cohere/openapi.yaml(11 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
Comment on lines
7178
to
7184
| $ref: '#/components/responses/ServiceUnavailable' | ||
| '504': | ||
| $ref: '#/components/responses/GatewayTimeout' | ||
| deprecated: true | ||
| x-fern-audiences: | ||
| - public | ||
| x-fern-examples: |
There was a problem hiding this comment.
🧩 Analysis chain
Verify operation scope and lint the spec
Add reason/sunset; also run linters to ensure deprecated keys are at valid levels and no duplicate description keys exist nearby.
Run:
🏁 Script executed:
#!/bin/bash
# Lint OpenAPI and enumerate all deprecations
set -euo pipefail
# Show deprecated fields with context
rg -nC2 $'\\bdeprecated:\\s*true\\b' src/libs/Cohere/openapi.yaml
# Optional: Redocly or Spectral if available
if command -v npx >/dev/null 2>&1; then
npx -y @redocly/cli@latest lint src/libs/Cohere/openapi.yaml || true
npx -y @stoplight/spectral-cli@latest lint -F warn src/libs/Cohere/openapi.yaml || true
fi
# Confirm info.version was bumped for this deprecation change
rg -nC1 $'^info:\\n|^version:\\s*' src/libs/Cohere/openapi.yamlLength of output: 12505
Fix OpenAPI validation error(s) and add deprecation metadata
redocly lint: 1 error, 20 warnings — address before merging.
- Schema type mismatch — src/libs/Cohere/openapi.yaml @ #/components/schemas/EmbedByTypeResponse/properties/embeddings (lines ~13947–13956): 'type: object' contains 'items'. Convert this node to a proper array schema (type: array + items) or remove the items from the object.
- Undefined required properties — define or remove required keys referenced but not declared (examples: CreateConnectorOAuth.required clientId/clientSecret/authorizeUrl/tokenUrl at ~13570–13576; EmbedByTypeResponse.required api_version at ~13941; EmbedFloatsResponse.required api_version at ~15253; requestBody required finetuned_model at ~6341; other similar warnings shown by the linter).
- Unused components — remove or reference unused components listed by the linter (e.g., CreateClusterJobRequest/Response ~13520/13559; FeedbackResponse ~16497; GetConnectorsLogsResponse ~16828; ListClusterJobsResponse ~17056).
- Deprecations and descriptions — many items are marked
deprecated: true(examples at lines 64–66, 169–172, 860–863, 1007–1008, 7179–7182). Add a deprecation reason/sunset field using a consistent approach (e.g., x-deprecation-reason / x-deprecation-sunset or explicit description text), ensuredeprecatedis applied at the correct schema/operation/response level, and remove any duplicatedescriptionkeys nearby. - After fixes, re-run linters and confirm info.version was bumped: npx @redocly/cli@latest lint src/libs/Cohere/openapi.yaml && npx @stoplight/spectral-cli@latest lint -F warn src/libs/Cohere/openapi.yaml
🤖 Prompt for AI Agents
In src/libs/Cohere/openapi.yaml around lines 7178–7184, the OpenAPI spec has
multiple lint failures: convert EmbedByTypeResponse.properties.embeddings from
an object-with-items to a proper array schema (type: array + items), add or
remove undefined required properties (e.g.,
CreateConnectorOAuth.clientId/clientSecret/authorizeUrl/tokenUrl,
EmbedByTypeResponse.api_version, EmbedFloatsResponse.api_version, requestBody
finetuned_model and any other required keys referenced but not declared), remove
or reference unused component schemas listed by the linter
(CreateClusterJobRequest/Response, FeedbackResponse, GetConnectorsLogsResponse,
ListClusterJobsResponse, etc.), and add consistent deprecation metadata (use
x-deprecation-reason and/or x-deprecation-sunset or explicit description text)
for items marked deprecated while ensuring deprecated is applied at the correct
level and duplicate description keys are removed; after making these edits, bump
info.version and re-run the linters: npx @redocly/cli@latest lint
src/libs/Cohere/openapi.yaml && npx @stoplight/spectral-cli@latest lint -F warn
src/libs/Cohere/openapi.yaml to confirm all errors/warnings are resolved.
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
Summary by CodeRabbit
Documentation
Chores