feat:Mark parameters and endpoints as deprecated in Cohere OpenAPI spec #261
Conversation
WalkthroughOpenAPI spec updates in src/libs/Cohere/openapi.yaml add deprecated: true to specific parameters and several path operations. The marked parameters include a ChatConnector-related parameter and search_queries_only. Multiple endpoints now carry deprecation flags near 504 Gateway Timeout response sections. No implementation logic changed. 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 (4)
src/libs/Cohere/openapi.yaml (4)
1128-1134: Deprecation is consistent; add human-visible cue.Consider prefixing the operation
summarywith “[DEPRECATED]” so rendered docs make this obvious.
1198-1204: Add deprecation rationale/replacement.Recommend adding a one-line note in the operation description pointing to the successor endpoint.
1343-1349: OK to deprecate; consider HTTP Deprecation/Sunset headers in runtime.If you own the server, emitting
DeprecationandSunsetheaders helps clients programmatically react.
1421-1427: Doc examples may need updates.If
x-fern-examplesreference this operation, ensure examples are updated or moved to the 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 (6)
src/libs/Cohere/openapi.yaml (6)
1501-1507: Deprecation OK; cross-reference SDKs.Verify language SDKs generated from this spec will carry the deprecation annotation (e.g., @deprecated tags).
6623-6629: Large spec section — no accidental path-level deprecation found.All
deprecated: trueoccurrences in src/libs/Cohere/openapi.yaml are on Operation Objects or inside components/schemas/properties; no Path Item-leveldeprecatedkeys detected.
63-69: Confirm deprecation scope forconnectors— param deprecated but connectors API & ChatConnector type still presentChatRequest.connectors is marked deprecated (src/libs/Cohere/openapi.yaml:60–66; src/libs/Cohere/Generated/Cohere.Models.ChatRequest.g.cs:34–36), but connector endpoints and the ChatConnector schema remain defined (openapi.yaml /v1/connectors ≈ 1075–1226; components/schemas/ChatConnector ≈ 12545–12574) and examples/code samples still reference connectors (openapi.yaml:232–302, 528–541).
- If the entire connectors feature is being retired: mark components/schemas/ChatConnector deprecated, add a short replacement pointer in its description, add metadata (e.g., x-sunset, x-replaced-by), and update/remove examples and generated models that reference connectors.
- If only the ChatRequest parameter is deprecated: add an explicit note in the ChatRequest/connectors description and examples clarifying that the connectors API and ChatConnector schema remain supported and document the recommended alternative workflow.
1004-1010: Deprecated markers are operation-level (sibling to responses) — no change required. Quick rg of src/libs/Cohere/openapi.yaml shows many 'deprecated: true' matches (e.g., lines 1007, 1131, 1202, 1275, 1346) with indentation consistent with operation-level placement; run an OpenAPI linter/validator for full-file validation.
7178-7184: Final deprecation hunk looks consistent — spec validated
openapi: 3.0.4 found at src/libs/Cohere/openapi.yaml:1 — basic schema-version check passes; no structural concerns.
1271-1277: Streaming/non‑streaming parity — deprecations are inconsistentv1/generate is marked as Legacy (migration note; ~lines 6450–6711) and many /v1/* endpoints are flagged deprecated (e.g. connectors block with deprecated: true around ~lines 1258–1285), but /v1/chat (~line 18) is not marked deprecated while /v2/chat (~line 7381) is the current streaming API. The schema also exposes both NonStreamedChatResponse and StreamedChatResponse (oneOf around ~lines 253–257). Deprecate the matching sync/stream variants together or add explicit migration notes for the un‑deprecated partner to avoid client drift.
| 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-fern-audiences: | ||
| - public | ||
| seed: |
There was a problem hiding this comment.
🛠️ Refactor suggestion
🧩 Analysis chain
Deprecate with guidance and timeline.
search_queries_only is now deprecated. Add 1–2 sentences in the description indicating the alternative and any removal date to prevent client confusion. Ensure generated SDKs surface this deprecation clearly.
Use this to check for docs/summary updates mentioning the alternative:
🏁 Script executed:
#!/bin/bash
rg -nC3 'search_queries_only' srcLength of output: 1749
Add deprecation guidance and removal timeline for search_queries_only
openapi.yaml marks search_queries_only as deprecated but its description has no alternative or removal date; the generated C# property is marked Obsolete with a generic message. Add 1–2 sentences to the OpenAPI property description naming the recommended alternative (if any) and a planned removal date, then regenerate SDKs so the deprecation (replacement + removal date) appears in generated docs/attributes.
- src/libs/Cohere/openapi.yaml (≈lines 168–171): extend the property description with alternative + removal date.
- src/libs/Cohere/Generated/Cohere.Models.ChatRequest.g.cs (≈lines 199–201): ensure Obsolete/XML-docs include the replacement and removal date after regeneration.
Summary by CodeRabbit