feat:Add deprecation flags to 2 params and 9 ops in Cohere OpenAPI spec #264
Conversation
WalkthroughThe OpenAPI spec file Changes
Estimated code review effort🎯 2 (Simple) | ⏱️ ~10 minutes Possibly related PRs
Poem
Pre-merge checks and finishing touches❌ Failed checks (1 inconclusive)
✅ 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 (9)
src/libs/Cohere/openapi.yaml (9)
168-174: LGTM; property-level deprecation is correctDeprecating
search_queries_onlyat the schema property level is valid. Consider adding a vendor extension with the reason and replacement for SDKs/docs.Example:
x-deprecation-reason: "Superseded by `search_mode`." x-replaced-by: "search_mode" x-sunset: "2025-12-31"
1007-1010: Operation correctly marked deprecated; add guidanceAdd
x-deprecation-reason,x-replaced-by, and, if applicable, aSunsettimeline to aid clients and docs.
1131-1134: Same as above: deprecation is fine; include reason/replacementProvide clients a migration path via vendor extensions and docs.
1201-1204: Add deprecation metadata for SDK/doc generationReason, replacement, and sunset date help automate warnings and upgrade guides.
1274-1277: OK to deprecate; consider Sunset header in gatewayKeep
deprecated: truehere; also plan aSunsetresponse header operationally.
1346-1349: Deprecation acknowledged; add migration hintInclude
x-replaced-bywith the new path/operationId.
1504-1507: Deprecation flag set; tag with reasonShort rationale improves generated docs.
6626-6629: Consistent; addx-older-than/version note if you use it internallyKeeps internal tooling consistent across deprecations.
7181-7184: Final deprecation hunk: OKNo issues; same suggestion to add reason/replacement.
📜 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
🔇 Additional comments (1)
src/libs/Cohere/openapi.yaml (1)
1424-1427: Good; mirror the change in changelog/release notesEnsure consumers are notified in release comms.
| 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.
🛠️ Refactor suggestion
🧩 Analysis chain
Do not place siblings next to $ref; deprecation here will be ignored by spec tools
deprecated, description, and x-fern-audiences are siblings of $ref under items. In OpenAPI, sibling keywords next to $ref are ignored by compliant tooling. Use allOf or move deprecation to the parent property/schema you intend to phase out.
Apply one of these:
Option A — wrap with allOf to retain annotations on the item schema:
- 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
+ items:
+ allOf:
+ - $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:
+ - publicOption B — if the intent is to deprecate the whole connectors property (not just the item type), put deprecated: true at the array property level instead of under items.
Run a quick lint to catch $ref-sibling issues and any schema violations:
🏁 Script executed:
#!/bin/bash
# Validate and lint the spec
npx --yes @redocly/cli@latest lint src/libs/Cohere/openapi.yaml || true
npx --yes [email protected] validate src/libs/Cohere/openapi.yamlLength of output: 8748
🏁 Script executed:
#!/bin/bash
set -euo pipefail
file="src/libs/Cohere/openapi.yaml"
if [ ! -f "$file" ]; then
echo "MISSING_FILE: $file not found"
exit 0
fi
echo "Searching for $ref blocks that include 'deprecated' or 'x-fern-audiences' within the following 12 lines..."
rg -n '\$ref:' "$file" | cut -d: -f1 | uniq | while read -r ln; do
sed -n "${ln},$((ln+12))p" "$file" > /tmp/block.txt
if rg -q 'deprecated:|x-fern-audiences:|x-fern-audience' /tmp/block.txt; then
echo "---- match starting at line $ln ----"
nl -ba -v $ln -w 6 -s' ' /tmp/block.txt
echo
fi
done
echo
echo "Searching for 'items:' blocks where $ref appears in the same block (possible $ref siblings under items)..."
rg -nU --pcre2 'items:\n(?:\s+.+\n){0,12}\s+\$ref:' "$file" || true
echo
echo "Snippet around lint error reported by redocly (~line 13940):"
start=13930
end=13960
sed -n "${start},${end}p" "$file" | nl -ba -v $start -w 6 -s' 'Length of output: 40
🏁 Script executed:
#!/bin/bash
file="src/libs/Cohere/openapi.yaml"
if [ ! -f "$file" ]; then
echo "MISSING_FILE: $file not found"
exit 0
fi
python3 - <<'PY'
import os
f='src/libs/Cohere/openapi.yaml'
with open(f,'r',encoding='utf-8') as fh:
lines=fh.readlines()
matches = []
for i,line in enumerate(lines):
if line.lstrip().startswith('items:'):
block = lines[i:i+20]
has_ref = any('$ref:' in l for l in block)
has_depr = any('deprecated:' in l for l in block)
has_desc = any('description:' in l for l in block)
has_x = any('x-fern-audiences' in l or 'x-fern-audience' in l for l in block)
if has_ref and (has_depr or has_x or has_desc):
matches.append((i+1, block))
if not matches:
# fallback: look for any $ref with deprecated/x-fern-audiences within +/-8 lines
for i,line in enumerate(lines):
if '$ref:' in line:
start=max(0,i-8)
end=min(len(lines), i+9)
block = lines[start:end]
has_depr = any('deprecated:' in l for l in block)
has_x = any('x-fern-audiences' in l or 'x-fern-audience' in l for l in block)
has_desc = any('description:' in l for l in block)
if has_depr or has_x or has_desc:
matches.append((start+1, block))
if not matches:
print('NO_MATCHES_FOUND')
else:
for start,block in matches:
print('---- match starting at line', start, '----')
for idx,ln in enumerate(block, start=start):
print(f'{idx:6d} {ln.rstrip()}')
print()
PYLength of output: 84195
Do not place siblings next to $ref — wrap items with allOf or mark the array deprecated (src/libs/Cohere/openapi.yaml: lines 63–69)
Sibling keys (description / deprecated / x-fern-audiences) next to $ref are ignored by OpenAPI tooling. Apply one of the two fixes below.
Option A — wrap with allOf to retain annotations on the item schema:
- 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
+ items:
+ allOf:
+ - $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:
+ - publicOption B — if the whole connectors array is being deprecated, move deprecated: true to the array property (the connectors: level) instead of under items.
📝 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.
| 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\"}, 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 |
🤖 Prompt for AI Agents
In src/libs/Cohere/openapi.yaml around lines 63 to 69, the schema under the
array items places sibling keys (description / deprecated / x-fern-audiences)
alongside a $ref which OpenAPI ignores; fix by either wrapping the referenced
schema in an allOf and moving the description/deprecated/x-fern-audiences into
that allOf entry so the annotations are applied, or (if the entire connectors
array is being deprecated) remove deprecated from items and instead set
deprecated: true on the connectors array property itself; implement one of these
two fixes so no sibling keys live next to $ref.
Summary by CodeRabbit