feat:Mark multiple Cohere API operations as deprecated in openapi.yaml #266
Conversation
WalkthroughThe OpenAPI spec at src/libs/Cohere/openapi.yaml adds deprecation annotations. Parameters conversation_id and search_queries_only are marked deprecated. Multiple operations now include deprecated: true flags, often alongside existing 504 GatewayTimeout response patterns. No response schemas or component definitions were changed. Changes
Estimated code review effort🎯 2 (Simple) | ⏱️ ~10 minutes Poem
Pre-merge checks and finishing touches✅ Passed checks (3 passed)
✨ Finishing touches🧪 Generate unit tests
Warning Tools execution failed with the following error: Failed to run tools: 13 INTERNAL: Received RST_STREAM with code 2 (Internal server error) 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 (3)
src/libs/Cohere/openapi.yaml (3)
168-174: Schema-level deprecation is valid; add migration hintMarking
search_queries_onlyas deprecated at the schema/property level is correct. Consider adding a brief replacement note in the description so SDK docs surface guidance (or a vendor extension if your tooling supports it).
1501-1507: LGTM: operation-level deprecationConsider adding a migration link in the operation description for developer UX.
6623-6629: LGTM: operation-level deprecationConfirm monitoring/alerts are set to watch residual traffic on deprecated routes.
📜 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)
🔇 Additional comments (7)
src/libs/Cohere/openapi.yaml (7)
1004-1010: LGTM: operation-level deprecation correctly placed
deprecated: trueat the operation level is valid. Ensure docs and SDKs regenerate and a changelog entry announces the deprecation window.
1128-1134: LGTM: operation-level deprecationSame as prior hunk; confirm downstream SDKs reflect this deprecation.
1198-1204: LGTM: operation-level deprecationConfirm any client examples referencing this endpoint are updated or tagged as deprecated.
1271-1277: LGTM: operation-level deprecationTrack a removal date and consider adding a “Sunset” policy note in docs.
1343-1349: LGTM: operation-level deprecationNo spec issues spotted here.
1421-1427: LGTM: operation-level deprecationEnsure server continues to accept traffic until the announced sunset.
7178-7184: LGTM: operation-level deprecationAll good. Include a deprecation notice in release notes.
| 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.
Fix invalid $ref siblings under items; move deprecation to the array/property level
items currently mixes $ref with sibling keys (description, deprecated, x-fern-audiences). In OpenAPI, a $ref object must not have other sibling fields; they will be ignored by most tooling. Place description/deprecated/x-fern-* on the array (property) schema, and keep items as a pure $ref.
Apply within this block:
items:
- $ref: '#/components/schemas/ChatConnector'
- description: "Accepts {\"id\": \"web-search\"} ... (RAG).\n\nCompatible Deployments: Cohere Platform\n"
- deprecated: true
- x-fern-audiences:
- - public
+ $ref: '#/components/schemas/ChatConnector'Then (outside the selected range), on the array/property (e.g., connectors:) level:
connectors:
type: array
description: "Accepts {\"id\": \"web-search\"} ... (RAG).\n\nCompatible Deployments: Cohere Platform\n"
deprecated: true
x-fern-audiences:
- public
items:
$ref: '#/components/schemas/ChatConnector'🤖 Prompt for AI Agents
In src/libs/Cohere/openapi.yaml around lines 63 to 69, the schema places
description/deprecated/x-fern-audiences as siblings of a $ref under items which
is invalid; remove those sibling fields from the items object so items contains
only the $ref, and move description, deprecated and x-fern-audiences up to the
array/property level (ensure the property has type: array and the moved fields),
leaving items as a pure $ref to the ChatConnector schema.
There was a problem hiding this comment.
Actionable comments posted: 0
♻️ Duplicate comments (8)
src/libs/Cohere/openapi.yaml (8)
1128-1134: Same as prior operation: add reason/replacement/sunset metadata.
1198-1204: Same as prior operation: add reason/replacement/sunset metadata.
1271-1277: Same as prior operation: add reason/replacement/sunset metadata.
1343-1349: Same as prior operation: add reason/replacement/sunset metadata.
1421-1427: Same as prior operation: add reason/replacement/sunset metadata.
1501-1507: Same as prior operation: add reason/replacement/sunset metadata.
6623-6629: Same as prior operation: add reason/replacement/sunset metadata.
7178-7184: Same as prior operation: add reason/replacement/sunset metadata.
🧹 Nitpick comments (2)
src/libs/Cohere/openapi.yaml (2)
168-174: Schema-property deprecation looks correct; add rationale and replacement.This correctly deprecates the property. Add a brief “Deprecated since ; use ” note and optionally vendor extensions like
x-deprecation-reason,x-replacement, andx-sunsetto aid SDKs/docs.
1004-1010: Operation deprecated: include deprecation metadata (reason, replacement, sunset).
deprecated: trueis valid. For clearer migration paths, append:
descriptionline mentioning deprecation and the preferred replacement.- Vendor hints:
x-deprecation-reason,x-replacement(operationId/path), andx-sunset(ISO date).Run this validator/inspector to list deprecated ops and catch item-level deprecations:
#!/bin/bash pip -q install openapi-spec-validator PyYAML >/dev/null python - <<'PY' import yaml, json from openapi_spec_validator import validate_v3_spec p = "src/libs/Cohere/openapi.yaml" spec = yaml.safe_load(open(p)) validate_v3_spec(spec) print("OK: OpenAPI validation passed.") ops=[] for path, item in (spec.get("paths") or {}).items(): for m, op in (item or {}).items(): if m.lower() in ("get","post","put","patch","delete","options","head","trace"): if op.get("deprecated") is True: ops.append({"path": path, "method": m.upper(), "operationId": op.get("operationId")}) print("Deprecated operations:", json.dumps(ops, indent=2)) def scan_params(params): bad=[] for param in (params or []): schema = param.get("schema") or {} if (schema.get("items") or {}).get("deprecated") is True: bad.append(param.get("name")) return bad bad=[] for path, item in (spec.get("paths") or {}).items(): bad += scan_params(item.get("parameters")) for m, op in (item or {}).items(): if m.lower() in ("get","post","put","patch","delete","options","head","trace"): bad += scan_params(op.get("parameters")) if bad: print("WARNING: parameters with items-level deprecations (likely misplaced):", bad) PY
📜 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)
🔇 Additional comments (1)
src/libs/Cohere/openapi.yaml (1)
63-69: ```shell
#!/bin/bash
set -euo pipefail
FILE="src/libs/Cohere/openapi.yaml"
if [ ! -f "$FILE" ]; then
echo "MISSING:$FILE"
exit 0
fi
echo "==== $FILE (lines with numbers) ===="
nl -ba "$FILE" | sed -n '1,200p'
echo "---- LINES 63-69 ----"
nl -ba "$FILE" | sed -n '63,69p'</blockquote></details> </blockquote></details> </details> <!-- This is an auto-generated comment by CodeRabbit for review status -->
Summary by CodeRabbit