feat:Mark deprecated operations and parameters in Cohere OpenAPI spec #274
Conversation
WalkthroughThe OpenAPI spec at src/libs/Cohere/openapi.yaml adds deprecated: true across numerous path operations and some path items, and marks two parameters (web-search option in ChatConnector and search_queries_only) as deprecated. No new endpoints or behaviors are 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: 0
🧹 Nitpick comments (8)
src/libs/Cohere/openapi.yaml (8)
63-69: Deprecation scope likely too broad for connectors; this flags the entire parameter/property.If the intent is to deprecate only the
"web-search"connector option (as per PR summary), marking this array/property asdeprecated: truewill deprecate all connectors in SDKs and docs. Prefer deprecating the specific"web-search"variant withinChatConnector(e.g., a oneOf member withid: const: web-searchmarkeddeprecated: true, or a vendor extension likex-deprecated-values: ['web-search']) and keep the parent container not deprecated. If the whole connectors feature is being sunset, clarify in the description and migration notes.Apply this local diff to avoid deprecating the entire container here:
- deprecated: trueThen, deprecate the
"web-search"variant at theChatConnectorschema (outside this hunk), for example:components: schemas: ChatConnector: oneOf: - type: object properties: id: const: web-search deprecated: true description: This connector is deprecated. Use <alternative> instead. - $ref: '#/components/schemas/ChatConnectorCustomOrOtherVariants'Would you like me to draft the exact schema change once you confirm where
ChatConnectoris defined?
168-174: Add a machine-readable default and a migration hint for the deprecated field.The description says “Defaults to false,” but there’s no
default: false. Add it so generators and validators honor the default. Also add a brief replacement hint (e.g., which field/feature supersedes this) via description or a vendor key.Apply this diff:
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" + default: false deprecated: true + x-deprecation-reason: "Superseded by <new_field_or_behavior>." + x-replacement: "<new_field_or_behavior>" x-fern-audiences: - publicPlease confirm the actual replacement so we can fill in
<new_field_or_behavior>.
1128-1134: Repeat: add per-operation deprecation notes.Mirror the prior comment: include a clear “use X instead” note and optional
x-sunset/x-replacementmetadata on this operation for better DX.
1198-1204: Deprecation is fine; ensure clients won’t get surprised.If behavior is unchanged for now, note that the endpoint remains functional until removal. Add a link to migration docs in
description.
1271-1277: Ensure consistency across all methods of the same path.If this path has multiple methods (GET/POST/etc.), verify all are consistently deprecated (or intentionally not). Inconsistencies confuse generators.
I can generate a repo scan to list any mixed-deprecation path items if you want.
1343-1349: Consider advertising the successor operation via vendor keys.Add
x-replacement: '<METHOD> <PATH or operationId>'to help SDKs and docs render precise guidance.
1421-1427: Optional: document Sunset header in responses.If you plan to serve a
SunsetHTTP header before removal, note it in the operationdescriptionand add a short example underx-fern-examples.
6623-6629: Doc hygiene: add a one-liner pointing to new API surface.Short, actionable deprecation sentence reduces support load. Keep it consistent across all deprecated ops.
📜 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 (3)
src/libs/Cohere/openapi.yaml (3)
1004-1010: Good: operation-level deprecation placed correctly. Add migration guidance and optional sunset metadata.
deprecated: trueis valid at the Operation level. For consumers, include actionable guidance: add a short deprecation line todescriptionpointing to the replacement operation/path and, optionally, a vendorx-sunsetdate andx-replacementto help SDKs surface better messages.If helpful, I can sweep the file and insert a standardized “Deprecated — use …” sentence for each deprecated operation once you provide the target replacements.
1501-1507: Check for duplicatedoperationIds post-deprecation.Even when deprecated,
operationIdmust remain unique. Verify no collisions were introduced by bulk edits.I can provide a quick script to parse and list duplicates if needed.
7178-7184: Verify deprecation placement (Parameter vs Schema).rg shows multiple
deprecated: trueoccurrences in src/libs/Cohere/openapi.yaml (examples: lines 63–66, 171, 862, 919, 959, 1007, 1131, 1201, 1274, 1346, 1424, 1504, 6626, 7181). Ensure parameter deprecations are on the Parameter Object (sibling of name/in) and schema/field deprecations are on the Schema Object — generators like Fern treat these differently and may hide non-deprecated options if misplaced. I can provide targeted fixes per location.
Summary by CodeRabbit