auto-docs: Update Cloud API spec #49
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 📝 WalkthroughWalkthroughThe pull request updates OpenAPI specification files with documentation and terminology refinements. In Estimated code review effort🎯 2 (Simple) | ⏱️ ~10 minutes
Possibly related PRs
Suggested reviewers
Pre-merge checks and finishing touches✅ Passed checks (3 passed)
Comment |
ℹ️ Redpanda/schema-registry API content change detectedNo structural change, nothing to display. Powered by Bump.sh |
ℹ️ Redpanda/http-proxy API content change detectedNo structural change, nothing to display. Powered by Bump.sh |
ℹ️ Redpanda/admin (branch: v1) API content change detectedNo structural change, nothing to display. Powered by Bump.sh |
ℹ️ Redpanda/admin (branch: v2) API content change detectedNo structural change, nothing to display. Powered by Bump.sh |
ℹ️ Redpanda/cloud-controlplane API content change detectedNo structural change, nothing to display. Powered by Bump.sh |
ℹ️ Redpanda/cloud-dataplane API content change detectedNo structural change, nothing to display. Powered by Bump.sh |
![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 (2)
cloud-dataplane/cloud-dataplane.yaml (2)
5582-5978: Remote MCP endpoints are well‑documented; one minor grammar tweak suggestedThe MCP server endpoints under
/v1/redpanda-connect/mcp-serversnow:
- Use clearer list/create/update/delete/start/stop descriptions.
- Expose filter, tag, and secret‑ID semantics that match the request/response schemas.
- Consistently tag operations with
Remote MCP, matching the new tag entry.Functionally and structurally this all looks correct.
One very small wording nit in the lint endpoint summary:
- Summary currently says
Lint a MCP tools configuration, but since “MCP” is pronounced “em‑see‑pee”, the article should be “an”.This is purely grammatical and optional, but keeps docs polished.
Proposed grammar fix for lint summary
- summary: Lint a MCP tools configuration + summary: Lint an MCP tools configurationBased on learnings, this YAML is generated from upstream proto; if you want this tweak, it should be applied in the cloudv2 proto comments rather than hand‑editing here.
7827-7853: Deploy transform summary casing is slightly inconsistent with neighboring summariesThe summary was changed to
Deploy Transformwhile nearby Wasm transform summaries use sentence case (List transforms,Delete transform,Get transform). For consistency with the rest of this tag group, you may want to keep it sentence‑cased as well.Optional style alignment
- summary: Deploy Transform + summary: Deploy transform
📜 Review details
Configuration used: Organization 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(1 hunks)cloud-dataplane/cloud-dataplane.yaml(25 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.
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: In the redpanda-data/api-docs repository's reference documentation, response schema titles do not display, but descriptions do. When reviewing proto sources that generate OpenAPI specs, suggest using description fields instead of title fields for content that should be visible in the documentation.
📚 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-controlplane/cloud-controlplane.yamlcloud-dataplane/cloud-dataplane.yaml
🔇 Additional comments (4)
cloud-dataplane/cloud-dataplane.yaml (4)
494-500: MCP config schema and linting descriptions are aligned with typesThe new descriptions for
ConfigurationYAMLSchema.config_schema,GetMCPServerServiceConfigSchemaResponse.configuration_yamls, and the MCP linting request/response (LintMCPConfigRequest.tools,LintMCPConfigResponse.lint_hints) correctly describe the map-of-tools shape and how YAML config and linting hints are keyed by tool name. They also match theToolschema’s YAML focus, so the semantics read clearly and consistently.Also applies to: 1224-1230, 1483-1499
1638-1660: MCP server list filtering docs are precise and consistentThe filter descriptions on
ListMCPServersRequest.Filter(display_name_contains,secret_id,tags[string]) now clearly explain substring vs exact-match semantics and the “must match all key-value pairs” behavior, andListMCPServersResponse.next_page_tokenmirrors pagination wording used elsewhere.
1942-2068: MCPServer schema and create/update payload docs look coherentThe updated descriptions for
MCPServer.id,tags,tools, andStatus.error, plus the clarified wording inMCPServerCreateandMCPServerUpdate, make the MCP server API surface much easier to understand. The new read‑onlyurlfield is consistent with similarurlusage onPipeline, and it’s correctly omitted from therequiredlist.All of this reads well and aligns with the surrounding resource model.
8251-8252: NewRemote MCPtag matches endpoint usageThe added tag (
name: Remote MCP, description about creating/managing MCP servers and configs) lines up with all updated MCP server operations and helps separate this surface from the existing Redpanda Connect Pipelines tag.
| /v1/network/{network_peering.network_id}/network-peerings: | ||
| post: | ||
| description: Create a Redpanda network peering. | ||
| description: Create a Redpanda network pering. |
There was a problem hiding this comment.
Fix typo in CreateNetworkPeering description in upstream proto
The description currently reads "Create a Redpanda network pering." — "pering" should be "peering". Because this OpenAPI spec is auto-generated, this needs to be corrected in the upstream proto definition rather than edited directly here. Based on learnings, specs in cloud-controlplane/ are generated from proto sources and should not be hand-edited.
🤖 Prompt for AI Agents
In cloud-controlplane/cloud-controlplane.yaml around line 5282, the OpenAPI
description for CreateNetworkPeering contains a typo ("pering" → "peering");
because this file is generated from proto sources, do not edit it directly.
Locate the corresponding proto RPC or message comment in the upstream proto
definition (search for "CreateNetworkPeering" or the description text), correct
the typo in the proto comment/option to "Create a Redpanda network peering.",
then regenerate the OpenAPI spec (run the proto->OpenAPI generation command used
by this repo) so the corrected description is emitted into
cloud-controlplane.yaml.
This PR updates the OpenAPI spec file for the Cloud API.
Triggered by commit: 2d90f5d72772403e5181f38f19a21f23fa637d65