auto-docs: Update Cloud API spec #44
Conversation
|
Important Review skippedAuto incremental reviews are disabled on this repository. Please check the settings in the CodeRabbit UI or the You can disable this status message by setting the 📝 WalkthroughWalkthroughThis pull request adds comprehensive Shadow Links support to both the control plane and data plane OpenAPI specifications. In the control plane specification, it introduces new resource schemas for shadow links with a full lifecycle state enum (creating, creation failed, deleting, deletion failed, active, paused), CRUD operation schemas, client options configurations, and HTTP endpoints for list, create, get, update, and delete operations. In the data plane specification, it adds new endpoints for shadow link operations including failover, metrics retrieval, and topic access, along with a FailOverBody schema. Both specifications include v1 and v2 variants of shadow link resources and client options. All changes are additive with no removals or refactoring of existing resources. Estimated code review effort🎯 3 (Moderate) | ⏱️ ~25 minutes
Possibly related PRs
Suggested reviewers
Pre-merge checks and finishing touches✅ Passed checks (3 passed)
Comment |
|
ℹ️ API content change detected: No structural change, nothing to display.
|
|
ℹ️ API content change detected: No structural change, nothing to display.
|
|
ℹ️ API content change detected: No structural change, nothing to display.
|
|
🤖 API structural change detected: Added (5)
|
|
🤖 API structural change detected: Added (5)
Modified (5)
|
![coderabbitai[bot]](https://avatars.githubusercontent.com/in/347564?s=60&v=4){kind=small}
There was a problem hiding this comment.
Actionable comments posted: 4
Caution
Some comments are outside the diff and can’t be posted inline due to platform limitations.
⚠️ Outside diff range comments (2)
cloud-controlplane/cloud-controlplane.yaml (2)
5144-5173: Grammar fix in description.“List Redpanda networks peerings.” → “List Redpanda network peerings.”
- description: List Redpanda networks peerings. + description: List Redpanda network peerings.
5261-5296: Typo in description.“Create a Redpanda network pering.” → “Create a Redpanda network peering.”
- description: Create a Redpanda network pering. + description: Create a Redpanda network peering.
♻️ Duplicate comments (1)
cloud-controlplane/cloud-controlplane.yaml (1)
3387-3413: Naming mismatch with client options (covered below).This block uses
source_redpanda_id; v1 client options usesource_cluster_id. See comment on Lines 4442-4523.
🧹 Nitpick comments (13)
cloud-dataplane/cloud-dataplane.yaml (9)
1064-1072: Add example payload for FailOverBody.Consider adding a minimal example to aid users (with and without shadow_topic_name).
509-515: Consistency: “connect cluster” → “Connect cluster”.Elsewhere we capitalize “Connect” when referring to Kafka Connect. Consider aligning.
4922-4928: Consistency: capitalize “Connect” in path param descriptions.Use “Connect cluster” for consistency with other endpoints.
Also applies to: 5043-5048
5581-5599: MCP Server endpoints: small copy/style polish.
- Use imperative mood in summaries for consistency (“Stop …” vs “Stops …”).
- summary: Stops a Redpanda Connect MCP server + summary: Stop a Redpanda Connect MCP serverAlso applies to: 5637-5640, 5675-5678, 5680-5689, 5719-5722, 5723-5732, 5819-5829, 5860-5863, 5905-5906
6375-6376: Pipeline endpoints: summary verb mood.Match other summaries by using imperative (“Stop …”).
- summary: Stops a Redpanda Connect pipeline + summary: Stop a Redpanda Connect pipeline
7833-7841: Multipart example: consider structured object example.The example is a stringified JSON. Prefer an object example for clarity under multipart schema.
7169-7178: Path naming: “topic” vs “topics”.List operation uses singular segment (/topic). Consider plural (/topics) for REST convention consistency. If generated from proto, this is optional.
8251-8253: Tag naming style.Consider title case (“Redpanda Connect MCP Servers”) to align with other tags.
Also applies to: 8261-8263
7089-7095: Param names: verify consistency of “name” vs “shadow_link_name”.Two patterns are used across endpoints. If intentional (per RPC proto), ignore; otherwise consider normalizing.
Also applies to: 7183-7196, 7235-7239
cloud-controlplane/cloud-controlplane.yaml (4)
756-759: Consider boundingredpanda_node_count.Add a sensible minimum (e.g., 1 or 3 for quorum) and possibly a maximum via
minimum/maximumto guide clients. As this file is generated, please add constraints in the upstream proto. Based on learnings, these specs are generated from protos.
4076-4099: Two TLS settings types can confuse clients.
v1.ShadowLinkClientOptionsreferencescontrolplane.v1.TLSSettingswhile v2 usescommon.v1.TLSSettings. If intentional, add clarifying doc strings (behavioral differences, precedence). Otherwise, consider unifying to a single TLS schema upstream. Based on learnings, update in protos.
4395-4440: Exposeidformat for clients.Consider annotating
idwithformat: uuid(if UUID) to improve client generation and validation. Apply upstream.
7266-7357: Shadow Links list/create endpoints: add operation result typing.POST returns a long‑running
Operation, butOperationResponseoneOf doesn’t includeCreateShadowLinkResponse. Add the ShadowLink responses toOperationResponse(and metadata if available) so SDKs can strongly type results. Update protos accordingly. Based on learnings, update upstream, not this YAML.
📜 Review details
Configuration used: CodeRabbit UI
Review profile: CHILL
Plan: Pro
Disabled knowledge base sources:
- Jira integration is disabled by default for public repositories
You can enable these sources in your CodeRabbit configuration.
📒 Files selected for processing (2)
cloud-controlplane/cloud-controlplane.yaml(16 hunks)cloud-dataplane/cloud-dataplane.yaml(26 hunks)
🧰 Additional context used
🧠 Learnings (2)
📓 Common learnings
Learnt from: kbatuigas
Repo: redpanda-data/api-docs PR: 40
File: cloud-controlplane/cloud-controlplane.yaml:1733-1738
Timestamp: 2025-11-26T19:18:28.591Z
Learning: For the redpanda-data/api-docs repository, the OpenAPI specification files in cloud-controlplane/ and cloud-dataplane/ are auto-generated from proto source files. Changes to these specs should be made in the upstream proto sources rather than directly editing the generated OpenAPI YAML files.
📚 Learning: 2025-11-26T19:18:28.591Z
Learnt from: kbatuigas
Repo: redpanda-data/api-docs PR: 40
File: cloud-controlplane/cloud-controlplane.yaml:1733-1738
Timestamp: 2025-11-26T19:18:28.591Z
Learning: For the redpanda-data/api-docs repository, the OpenAPI specification files in cloud-controlplane/ and cloud-dataplane/ are auto-generated from proto source files. Changes to these specs should be made in the upstream proto sources rather than directly editing the generated OpenAPI YAML files.
Applied to files:
cloud-dataplane/cloud-dataplane.yamlcloud-controlplane/cloud-controlplane.yaml
🔇 Additional comments (14)
cloud-dataplane/cloud-dataplane.yaml (3)
7047-7084: Shadow Links (Data Plane): additive surface LGTM; confirm generated upstream.Endpoints and schemas are additive and consistent. Please confirm these YAMLs were generated from the referenced cloudv2 proto commit to avoid drift with source of truth. Based on learnings, OpenAPI in this repo is auto-generated from proto.
Also applies to: 7085-7130, 7131-7168, 7169-7224, 7225-7267
1485-1492: MCP config/tooling descriptions: LGTM.Clearer descriptions for MCP tools/server config and linting.
Also applies to: 1970-1972, 2035-2037, 2064-2066
1640-1650: ListMCPServersRequest.Filter descriptions: LGTM.Helpful, concise filter docs.
cloud-controlplane/cloud-controlplane.yaml (11)
1147-1153: CreateShadowLinkOperation: LGTM.Wrapper matches existing operation pattern.
1409-1413: DeleteShadowLinkOperation: LGTM.Consistent with other delete operations.
2159-2166: ListShadowLinksRequest.Filter: LGTM.Filter fields look coherent with query params.
3363-3371: ShadowLink.State: LGTM.Lifecycle enum is clear and complete.
3415-3433: ShadowLinkListItem: LGTM.Slim list representation is appropriate.
3484-3499: ShadowLinkUpdate: LGTM.Updatable fields align with create/read models.
4168-4173: v1.CreateShadowLinkRequest: LGTM.Shape is minimal and consistent.
4302-4307: v1.GetShadowLinkResponse: LGTM.
4308-4318: v1.ListShadowLinksResponse: LGTM.
7359-7434: Shadow Links get/delete: LGTM.Status codes and shapes are consistent.
7436-7494: Shadow Link update: LGTM.Patch schema matches the v1 models; returns LRO wrapper.
| - name: ShadowLinkService | ||
| - description: Manage Redpanda Cloud shadow links for data replication. | ||
| name: Shadow Links | ||
| - description: See information about the organization the current user belongs to. |
There was a problem hiding this comment.
Extra tag “ShadowLinkService” not used.
Operations use the “Shadow Links” tag. Drop the unused “ShadowLinkService” tag or retag operations consistently to avoid duplicate groups in rendered docs.
🤖 Prompt for AI Agents
In cloud-controlplane/cloud-controlplane.yaml around lines 7810-7813, the
OpenAPI spec contains an unused tag "ShadowLinkService" while operations are
tagged "Shadow Links"; remove the unused "ShadowLinkService" tag or make tags
consistent by either renaming the tag entry to "Shadow Links" or updating all
operation tag values to "ShadowLinkService" so there is a single consistent tag
group; ensure the tags list and each operation's tags field match exactly and
regenerate/validate the OpenAPI document.
| type: string | ||
| display_name: | ||
| description: User-friendly MCP server name. | ||
| description: User-friendly MCP servers name. | ||
| type: string | ||
| resources: |
There was a problem hiding this comment.
Grammar: “servers name” → “server name”.
“MCP servers name” should be singular possessive.
- description: User-friendly MCP servers name.
+ description: User-friendly MCP server name.📝 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.
| type: string | |
| display_name: | |
| description: User-friendly MCP server name. | |
| description: User-friendly MCP servers name. | |
| type: string | |
| resources: | |
| type: string | |
| display_name: | |
| description: User-friendly MCP server name. | |
| type: string | |
| resources: |
🤖 Prompt for AI Agents
In cloud-dataplane/cloud-dataplane.yaml around lines 2046–2050, the description
"User-friendly MCP servers name." is grammatically incorrect; replace it with a
singular possessive phrase such as "User-friendly MCP server's name." or reword
to "User-friendly name of the MCP server." to fix the grammar and convey the
same meaning.
| readOnly: true | ||
| title: |- | ||
| The Client ID for the Kafka RPC requests sent by this cluster to the | ||
| The Client ID for the Kafka RPC requests setn by this cluster to the | ||
| source cluster | ||
| type: string | ||
| connection_timeout_ms: |
There was a problem hiding this comment.
Typo: “setn” → “sent”.
Title under ShadowLinkClientOptions.client_id has a typo.
- The Client ID for the Kafka RPC requests setn by this cluster to the
+ The Client ID for the Kafka RPC requests sent by this cluster to the📝 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.
| readOnly: true | |
| title: |- | |
| The Client ID for the Kafka RPC requests sent by this cluster to the | |
| The Client ID for the Kafka RPC requests setn by this cluster to the | |
| source cluster | |
| type: string | |
| connection_timeout_ms: | |
| readOnly: true | |
| title: |- | |
| The Client ID for the Kafka RPC requests sent by this cluster to the | |
| source cluster | |
| type: string | |
| connection_timeout_ms: |
🤖 Prompt for AI Agents
In cloud-dataplane/cloud-dataplane.yaml around lines 2860 to 2865, the title
string for ShadowLinkClientOptions.client_id contains a typo ("setn"); update
the title to use the correct word "sent" so it reads "The Client ID for the
Kafka RPC requests sent by this cluster to the source cluster". Ensure YAML
formatting and indentation are preserved.
vbotbuildovich
force-pushed
the
update-branch-api
branch
from
33f47a1 to
c6ddb69
Compare
| /v1/network/{network_peering.network_id}/network-peerings: | ||
| post: | ||
| description: Create a Redpanda network peering. | ||
| description: Create a Redpanda network pering. |
This PR updates the OpenAPI spec file for the Cloud API.
Triggered by commit: 45c9f33726dcbbd864e5ad15605d82703d2b2d44