feat:Deprecate params and 504-response operations in Cohere openapi.yaml #258
Conversation
WalkthroughMarked specific parameters and multiple operations as deprecated in src/libs/Cohere/openapi.yaml by adding deprecated: true. Targets include the ChatConnector options parameter (items), the search_queries_only boolean parameter, and several endpoints that include a 504 GatewayTimeout response. No other changes. 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: 2
🧹 Nitpick comments (8)
src/libs/Cohere/openapi.yaml (8)
1128-1134: Repeat deprecation metadata consistently.Mirror the same deprecation rationale vendor field here for consistent docs across SDKs and portals.
'504': $ref: '#/components/responses/GatewayTimeout' deprecated: true + x-deprecation-reason: "Superseded operation; refer to migration guidance."
1198-1204: Add a deprecation rationale.Surface a short message so generators can annotate the method with actionable notes.
'504': $ref: '#/components/responses/GatewayTimeout' deprecated: true + x-deprecation-reason: "Deprecated; use the replacement endpoint."
1271-1277: Doc-quality polish for deprecation.Same as above—include a reason to aid developers scanning generated SDK docs.
'504': $ref: '#/components/responses/GatewayTimeout' deprecated: true + x-deprecation-reason: "Deprecated; see docs for alternatives."
1343-1349: Consistent deprecation messaging.Apply the same
x-deprecation-reasonpattern here.'504': $ref: '#/components/responses/GatewayTimeout' deprecated: true + x-deprecation-reason: "Deprecated operation."
1421-1427: Optional: include planned removal timeline (vendor field).If you have an internal EOL date, expose it via a vendor key (e.g.,
x-sunset) to help clients plan. If not, skip.'504': $ref: '#/components/responses/GatewayTimeout' deprecated: true + x-deprecation-reason: "Deprecated operation." + x-sunset: "YYYY-MM-DD"
1501-1507: Same deprecation rationale as siblings.Keep messaging uniform across all deprecated operations.
'504': $ref: '#/components/responses/GatewayTimeout' deprecated: true + x-deprecation-reason: "Deprecated operation."
1004-1010: Operation-level deprecation: add guidance for consumers.Multiple operations in src/libs/Cohere/openapi.yaml are marked
deprecated: true(examples: lines 1005–1008, 1129–1132, 1199–1202, 1272–1275, 1344–1347, 1422–1425, 1502–1505, 6624–6627, 7179–7182). Add a short deprecation sentence in each operation's description or add anx-deprecation-reasonso SDKs/docs show migration steps. Keep 5xx responses unchanged.If there’s no description yet, append one:
'504': $ref: '#/components/responses/GatewayTimeout' deprecated: true + x-deprecation-reason: "This endpoint is superseded by a newer path; see API docs for migration."Validate:
rg -nC2 $'^\\s*deprecated:\\s*true\\b' src/libs/Cohere/openapi.yaml
63-69: Mark the parameter as deprecated (not only the schema).OpenAPI 3.0.4 allows
deprecatedon both Schema and Parameter objects. (spec.openapis.org) If your intent is to deprecate the parameter (not just the array/schema), adddeprecated: trueon the Parameter Object wherename: connectorsis declared and include a short vendor note (x-deprecation-reason) so SDKs/docs surface migration guidance.Location: src/libs/Cohere/openapi.yaml (around lines 63–69 —
deprecated: trueis currently on the schema/$ref).Suggested docs vendor note (optional):
description: "Accepts ... (RAG).\n\nCompatible Deployments: Cohere Platform\n" deprecated: true + x-deprecation-reason: "Connectors via this field are being phased out; see migration guidance."
📜 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)
6623-6629: Large spec section — deprecated is operation-scoped.Confirmed
deprecated: trueis at src/libs/Cohere/openapi.yaml:6626 at the same indentation level as operation properties (responses), so it deprecates only that operation, not the entire path.
| 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.
🧩 Analysis chain
Include a deprecation note and confirm behavior consistency.
search_queries_only is now deprecated. Add a one‑line reason so clients know the alternative, and verify server behavior remains backward‑compatible while deprecated.
You can append a reason:
deprecated: true
+ x-deprecation-reason: "Use the new queries-inspection workflow; this flag will be removed in a future release."And lint the spec:
🏁 Script executed:
#!/bin/bash
npx -y @redocly/cli@latest lint src/libs/Cohere/openapi.yamlLength of output: 8369
Add a deprecation note for search_queries_only and fix OpenAPI lint failures.
Add the one-line deprecation reason below, then fix the linter error(s) and warnings and re-run the linter.
Suggested diff:
deprecated: true
+ x-deprecation-reason: "Use the new queries-inspection workflow; this flag will be removed in a future release."Linter output to address:
- ERROR: src/libs/Cohere/openapi.yaml:13949:13 — Schema type mismatch: 'object' type should not contain 'items' field (#/components/schemas/EmbedByTypeResponse/properties/embeddings/items).
- WARNINGS: multiple "Required property '... ' is undefined" at src/libs/Cohere/openapi.yaml lines 13572, 13573, 13574, 13575, 13943, 15255, 6343, 17502, 16611, 17209, 17211, etc.
Actions required:
- Add the x-deprecation-reason line.
- Fix the EmbedByTypeResponse schema error and define/restore any required properties referenced by the spec (or remove them from required).
- Re-run: npx -y @redocly/cli@latest lint src/libs/Cohere/openapi.yaml and attach the updated output.
- After the spec validates, confirm (or document) that deprecating search_queries_only is backward-compatible on the server side.
Committable suggestion skipped: line range outside the PR's diff.
🤖 Prompt for AI Agents
In src/libs/Cohere/openapi.yaml around lines 168 to 174, add an
x-deprecation-reason one-line note for the search_queries_only field, then fix
the OpenAPI linter errors by correcting the EmbedByTypeResponse schema (remove
the items attribute from any property typed as "object" or change the property
type to "array" if it actually contains items) and resolve the multiple
"Required property '... ' is undefined" warnings by either defining the missing
properties under the appropriate schema or removing them from the required
arrays where they are not present; after making these changes re-run npx -y
@redocly/cli@latest lint src/libs/Cohere/openapi.yaml and attach the lint
output, and finally document or confirm that deprecating search_queries_only is
backward-compatible on the server side.
| $ref: '#/components/responses/ServiceUnavailable' | ||
| '504': | ||
| $ref: '#/components/responses/GatewayTimeout' | ||
| deprecated: true | ||
| x-fern-audiences: | ||
| - public | ||
| x-fern-examples: |
There was a problem hiding this comment.
🧩 Analysis chain
Final deprecation hunk: add rationale and lint.
Add the vendor reason here as well and re-run the linter to ensure no structural regressions.
'504':
$ref: '#/components/responses/GatewayTimeout'
deprecated: true
+ x-deprecation-reason: "Deprecated operation."🏁 Script executed:
#!/bin/bash
npx -y @redocly/cli@latest lint src/libs/Cohere/openapi.yamlLength of output: 8369
Final deprecation hunk: add rationale and fix linter errors.
- Add the vendor deprecation reason next to
deprecated: trueand re-run the linter. Apply:
'504':
$ref: '#/components/responses/GatewayTimeout'
deprecated: true
+ x-deprecation-reason: "Deprecated operation."- Linter currently fails: 1 error and 20 warnings. Fix the error at src/libs/Cohere/openapi.yaml:13949 (#/components/schemas/EmbedByTypeResponse/properties/embeddings/items) — schema uses
type: objectbut containsitems(change totype: arrayor removeitems). Also address undefined required properties in CreateConnectorOAuth (lines ~13572–13575) and undefinedapi_versionin embed responses (lines ~13943, 15255), then re-run:
npx -y @redocly/cli@latest lint src/libs/Cohere/openapi.yaml🤖 Prompt for AI Agents
In src/libs/Cohere/openapi.yaml around lines 7178-7184 (and also address related
issues at ~13572-13575, 13943, 13949, and 15255): add a vendor deprecation
reason next to any deprecated: true entries (x-vendor or vendorExtensions per
your spec/linter), fix the schema at
#/components/schemas/EmbedByTypeResponse/properties/embeddings/items (line
~13949) by changing type: object to type: array if items is required or remove
the items field and keep object, correct undefined required properties in
CreateConnectorOAuth (lines ~13572–13575) by either defining those properties in
the schema or removing them from required, and add the missing api_version
property in the embed response schemas (lines ~13943 and ~15255) with an
appropriate type; after making these changes re-run npx -y @redocly/cli@latest
lint src/libs/Cohere/openapi.yaml to confirm the linter is clean.
Summary by CodeRabbit