feat:Mark parameters and operations as deprecated in Cohere OpenAPI #265
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
WalkthroughAdds deprecated: true markers to parameters and multiple operation objects in src/libs/Cohere/openapi.yaml, deprecating specific flags and endpoints across the OpenAPI spec. No schema or runtime logic changes; only contract-level deprecation annotations were introduced. Changes
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)
168-174: Schema-level deprecation is fine; add rationale and migration hints.Add explicit reason and replacement to improve SDK/portal clarity; consider prefixing description with “Deprecated”.
search_queries_only: type: boolean description: "Defaults to `false`.\n\nWhen `true`, the response will only contain a list of generated search queries, but no search will take place, and no reply from the model to the user's `message` will be generated.\n\nCompatible Deployments: Cohere Platform, Azure, AWS Sagemaker/Bedrock, Private Deployments\n" deprecated: true + x-deprecation-reason: "Superseded by <new flag/behavior>." + x-replacement: "<replacement flag or request shape>" x-fern-audiences: - public
1004-1010: Operation deprecated: include sunset and migration metadata.Add deprecation reason and a target removal date to communicate timelines.
'504': $ref: '#/components/responses/GatewayTimeout' deprecated: true + x-deprecation-reason: "Endpoint replaced by <new path>." + x-replacement: "<new operationId or path>" + x-sunset-date: "2026-03-31"
1128-1134: Mirror deprecation metadata on this operation as well.'504': $ref: '#/components/responses/GatewayTimeout' deprecated: true + x-deprecation-reason: "Endpoint replaced by <new path>." + x-replacement: "<new operationId or path>" + x-sunset-date: "2026-03-31"
1198-1204: Add reason/replacement/sunset to deprecation for consistency.'504': $ref: '#/components/responses/GatewayTimeout' deprecated: true + x-deprecation-reason: "Endpoint replaced by <new path>." + x-replacement: "<new operationId or path>" + x-sunset-date: "2026-03-31"
1271-1277: Same note: enrich deprecation with actionable metadata.'504': $ref: '#/components/responses/GatewayTimeout' deprecated: true + x-deprecation-reason: "Endpoint replaced by <new path>." + x-replacement: "<new operationId or path>" + x-sunset-date: "2026-03-31"
1343-1349: Add deprecation rationale and sunset to aid client migration.'504': $ref: '#/components/responses/GatewayTimeout' deprecated: true + x-deprecation-reason: "Endpoint replaced by <new path>." + x-replacement: "<new operationId or path>" + x-sunset-date: "2026-03-31"
1421-1427: Operational deprecation: include guidance fields.'504': $ref: '#/components/responses/GatewayTimeout' deprecated: true + x-deprecation-reason: "Endpoint replaced by <new path>." + x-replacement: "<new operationId or path>" + x-sunset-date: "2026-03-31"
1501-1507: Provide migration metadata alongside deprecation.'504': $ref: '#/components/responses/GatewayTimeout' deprecated: true + x-deprecation-reason: "Endpoint replaced by <new path>." + x-replacement: "<new operationId or path>" + x-sunset-date: "2026-03-31"
6623-6629: Add reason and sunset date for this deprecated operation.'504': $ref: '#/components/responses/GatewayTimeout' deprecated: true + x-deprecation-reason: "Endpoint replaced by <new path>." + x-replacement: "<new operationId or path>" + x-sunset-date: "2026-03-31"
7178-7184: Same deprecation metadata recommendation here.'504': $ref: '#/components/responses/GatewayTimeout' deprecated: true + x-deprecation-reason: "Endpoint replaced by <new path>." + x-replacement: "<new operationId or path>" + x-sunset-date: "2026-03-31"
📜 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
63
to
69
| items: | ||
| $ref: '#/components/schemas/ChatConnector' | ||
| description: "Accepts `{\"id\": \"web-search\"}`, and/or the `\"id\"` for a custom [connector](https://docs.cohere.com/docs/connectors), if you've [created](https://docs.cohere.com/v1/docs/creating-and-deploying-a-connector) one.\n\nWhen specified, the model's reply will be enriched with information found by querying each of the connectors (RAG).\n\nCompatible Deployments: Cohere Platform\n" | ||
| deprecated: true | ||
| x-fern-audiences: | ||
| - public | ||
| conversation_id: |
There was a problem hiding this comment.
🧩 Analysis chain
Avoid $ref siblings under items (OAS 3.0); use allOf or confirm OAS 3.1. Also verify you intend to deprecate the entire connectors item, not just a specific connector variant.
- If this spec is OpenAPI 3.0.x,
$refcannot have siblings (description,deprecated,x-*). Wrap withallOf. If it's 3.1, siblings are allowed—still confirm your generators (Fern/SDKs) support it. - Deprecating at the array
itemslevel marks every item deprecated. If the goal is to deprecate only theweb-searchconnector, deprecate that specific schema/oneOf branch instead, not the entire item type.
Suggested fix (3.0‑safe):
- items:
- $ref: '#/components/schemas/ChatConnector'
- description: "Accepts {\"id\": \"web-search\"} ... Compatible Deployments: Cohere Platform\n"
- deprecated: true
- x-fern-audiences:
- - public
+ items:
+ allOf:
+ - $ref: '#/components/schemas/ChatConnector'
+ description: "Accepts {\"id\": \"web-search\"} ... Compatible Deployments: Cohere Platform\n"
+ deprecated: true
+ x-fern-audiences:
+ - public
+ x-deprecation-reason: "Connector array items are deprecated; prefer tool-calls or new connector API."
+ x-replacement: "<point to new schema/field>"Quick validation script:
🏁 Script executed:
#!/bin/bash
# Validate OAS version and run Python-based validators.
set -euo pipefail
FILE=src/libs/Cohere/openapi.yaml
echo -n "openapi version: "; awk '/^openapi:/{print $2}' "$FILE" || true
pip -q install openapi-spec-validator openapi-schema-validator pyyaml >/dev/null
python - <<'PY'
import sys, yaml
from openapi_spec_validator import validate_spec
with open("src/libs/Cohere/openapi.yaml","r") as f:
spec=yaml.safe_load(f)
try:
validate_spec(spec) # Validates OAS 3.0.x
print("openapi-spec-validator: OK (3.0.x semantics)")
except Exception as e:
print("openapi-spec-validator: FAILED ->", e)
PYLength of output: 294
Fix $ref siblings in OpenAPI 3.0.4 and narrow deprecation scope
Verified: openapi: 3.0.4 (openapi-spec-validator: OK). In OAS 3.0 a $ref must be the only key in its schema object — wrap the $ref in allOf (or upgrade to OAS 3.1 and confirm generator support). Also: deprecating at the array items level deprecates every connector; if only the web-search connector should be deprecated, deprecate that specific schema/oneOf branch instead.
Location: src/libs/Cohere/openapi.yaml (lines 63–69).
Suggested 3.0‑safe fix:
- items:
- $ref: '#/components/schemas/ChatConnector'
- description: "Accepts {\"id\": \"web-search\"} ... Compatible Deployments: Cohere Platform\n"
- deprecated: true
- x-fern-audiences:
- - public
+ items:
+ allOf:
+ - $ref: '#/components/schemas/ChatConnector'
+ description: "Accepts {\"id\": \"web-search\"} ... Compatible Deployments: Cohere Platform\n"
+ deprecated: true
+ x-fern-audiences:
+ - public
+ x-deprecation-reason: "Connector array items are deprecated; prefer tool-calls or new connector API."
+ x-replacement: "<point to new schema/field>"📝 Committable suggestion
‼️ IMPORTANT
Carefully review the code before committing. Ensure that it accurately replaces the highlighted code, contains no missing lines, and has no issues with indentation. Thoroughly test & benchmark the code to ensure it meets the requirements.
Suggested change
| items: | |
| $ref: '#/components/schemas/ChatConnector' | |
| description: "Accepts `{\"id\": \"web-search\"}`, and/or the `\"id\"` for a custom [connector](https://docs.cohere.com/docs/connectors), if you've [created](https://docs.cohere.com/v1/docs/creating-and-deploying-a-connector) one.\n\nWhen specified, the model's reply will be enriched with information found by querying each of the connectors (RAG).\n\nCompatible Deployments: Cohere Platform\n" | |
| deprecated: true | |
| x-fern-audiences: | |
| - public | |
| conversation_id: | |
| items: | |
| allOf: | |
| - $ref: '#/components/schemas/ChatConnector' | |
| description: "Accepts {\"id\": \"web-search\"} ... Compatible Deployments: Cohere Platform\n" | |
| deprecated: true | |
| x-fern-audiences: | |
| - public | |
| x-deprecation-reason: "Connector array items are deprecated; prefer tool-calls or new connector API." | |
| x-replacement: "<point to new schema/field>" |
🤖 Prompt for AI Agents
In src/libs/Cohere/openapi.yaml around lines 63 to 69, the schema uses a $ref
alongside sibling keys (invalid in OpenAPI 3.0) and marks deprecation at the
array items level (which deprecates all connectors). Fix by replacing any object
that currently contains "$ref" plus other keys with an allOf containing the $ref
and then additional schemas for the other keys (e.g., allOf: - $ref: ...; -
type/object with properties), and move the deprecated: true flag from the
overall items schema to only the specific connector branch (the web-search
schema) by adding deprecated: true inside that web-search schema/oneOf branch so
only that connector is deprecated.
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