feat:Deprecate params and nine operations in Cohere OpenAPI spec #267
Conversation
WalkthroughAdded deprecation annotations to the Cohere OpenAPI spec. Two parameters (ChatConnector IDs list and search_queries_only) are marked deprecated. Nine operations are also marked deprecated in their operation metadata. No schemas or data types were 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 (9)
src/libs/Cohere/openapi.yaml (9)
168-174: Encode the default in the schema, not just the description.The description states “Defaults to false”; add an explicit default for generators and validators.
Apply:
search_queries_only: type: boolean + default: false 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
1004-1010: Deprecation flag on operation looks good; add rationale/plan.Consider adding x-deprecation-reason and a planned removal date (and/or a Sunset response header) to guide clients.
1128-1134: LGTM; consider adding deprecation metadata.Add x-deprecation-reason and a target sunset date to aid SDK/docs generation.
1198-1204: LGTM; surface alternatives.If there’s a replacement operation, reference it via description or an x-replaced-by extension.
1271-1277: LGTM; optional Sunset header.Exposing a Sunset header in 2xx responses helps automated client warnings.
1343-1349: LGTM; ensure changelog/docs reflect this deprecation.Sync API docs and release notes so users see the deprecation immediately.
1421-1427: LGTM; tag as Deprecated for discoverability.Optionally add a “Deprecated” tag to group these in rendered docs.
6623-6629: LGTM; consider x-sunset/x-removal-date conventions.If your tooling supports it, add custom dates to enable timeline dashboards.
7178-7184: LGTM; ensure monitoring for deprecated usage.Add metrics on these routes so you can track remaining traffic before removal.
📜 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)
1501-1507: LGTM; verify SDKs regen with deprecation annotations.Regenerate and smoke‑test major SDKs to confirm warnings appear and no breaking diffs.
| 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.
❓ Verification inconclusive
Fix $ref siblings and confirm intended deprecation target (schema items vs parameter).
In OpenAPI 3.0, sibling keys next to $ref are ignored/invalid. If the spec is 3.0.x, wrap the ref in allOf to attach description/deprecated; if you intend to deprecate the whole parameter (not each item), set deprecated at the Parameter Object level instead of items.
Apply this safe 3.0-compatible tweak:
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
+ 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: trueIf only the built‑in value "web-search" is deprecated (not the entire connector mechanism), consider deprecating that enum value in the ChatConnector schema via an extension (e.g., x-enum-deprecated) instead of deprecating all items.
Fix $ref siblings and confirm intended deprecation target (schema items vs parameter)
File: src/libs/Cohere/openapi.yaml (lines 63–69)
In OpenAPI 3.0, any siblings next to a $ref are ignored; wrap the referenced schema in allOf to attach description/deprecated. (swagger.io)
If you intend to deprecate the whole parameter, set deprecated on the Parameter Object; for schema/property-level deprecation use the schema’s deprecated flag (or deprecate the enum value). (spec.openapis.org)
Apply this safe 3.0-compatible tweak:
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
+ 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: trueIf only the built-in value "web-search" is deprecated (not the entire connector mechanism), deprecate that enum value in ChatConnector via a vendor extension (e.g., x-enum-deprecated) instead of deprecating all items.
Committable suggestion skipped: line range outside the PR's diff.
🤖 Prompt for AI Agents
In src/libs/Cohere/openapi.yaml around lines 63-69, siblings next to a $ref are
being used (description/deprecated) which OpenAPI 3.0 ignores; wrap the
referenced schema in an allOf and move any description/deprecated into that
allOf entry so the metadata is preserved, and if you meant to deprecate the
entire parameter set the deprecated flag on the Parameter Object rather than the
schema; if you only want to deprecate the specific enum value "web-search"
instead of the whole items/schema, mark that enum value as deprecated using a
vendor extension such as x-enum-deprecated on the ChatConnector enum entry.
Summary by CodeRabbit