auto-docs: Update Cloud API spec

[vbotbuildovich]

This PR updates the OpenAPI spec file for the Cloud API.
Triggered by commit: 6099ca8994b6fce5bb82951cea201030fdf67179

[coderabbitai]

Important

Review skipped

Auto incremental reviews are disabled on this repository.

Please check the settings in the CodeRabbit UI or the .coderabbit.yaml file in this repository. To trigger a single review, invoke the @coderabbitai review command.

You can disable this status message by setting the reviews.review_status to false in the CodeRabbit configuration file.

📝 Walkthrough

Walkthrough

This pull request updates API schema definitions across two configuration files. In cloud-controlplane, private URL descriptions for ServerlessCluster components are rephrased for consistency. In cloud-dataplane, a new ServiceAccount type is introduced with client_id and client_secret fields, and this type is integrated into Pipeline, PipelineCreate, and PipelineUpdate schemas to enable service account specification during pipeline operations. Minor documentation clarifications are applied to several field descriptions without altering data structures.

Sequence Diagram(s)

These changes are primarily schema definition and documentation updates without modifications to control flow or feature interactions, making sequence diagrams unnecessary.

Estimated code review effort

🎯 2 (Simple) | ⏱️ ~12 minutes

The changes consist of straightforward schema extensions and description updates. The cloud-controlplane modifications are cosmetic documentation rewrites. The cloud-dataplane changes introduce a new ServiceAccount type and apply it consistently across three related schemas—a repetitive pattern that simplifies review. No complex logic, behavior changes, or intricate interactions are introduced.

Suggested reviewers

• JakeSCahill
• kbatuigas
• micheleRP

Pre-merge checks and finishing touches

✅ Passed checks (3 passed)

Check name	Status	Explanation
Title Check	✅ Passed	The pull request title "auto-docs: Update Cloud API spec" is directly related to the changeset, which updates OpenAPI specification files in both cloud-controlplane and cloud-dataplane. The title accurately captures the primary activity of updating the Cloud API specification, with the "auto-docs" prefix indicating this is an automated documentation update. While the title could be more specific about the nature of the changes (such as adding ServiceAccount support or updating documentation), it is sufficiently clear and specific for a teammate scanning the commit history to understand that the API spec was updated.
Docstring Coverage	✅ Passed	No functions found in the changes. Docstring coverage check skipped.
Description check	✅ Passed	The pull request description accurately explains the purpose of the changes: updating the OpenAPI spec file for the Cloud API.

---

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

[coderabbitai]

Actionable comments posted: 0

🧹 Nitpick comments (4)

cloud-dataplane/cloud-dataplane.yaml (4)

1822-1828: Add descriptions to ServiceAccount fields for API clarity.

The new ServiceAccount schema lacks field descriptions. client_id and client_secret should include descriptions to guide API consumers on their purpose and format.

 ServiceAccount: properties: client_id: + description: The client identifier for the service account. type: string client_secret: + description: The client secret for authentication purposes. type: string type: object

---

1399-1400: Add description to service_account field in Pipeline schema.

The new service_account field in the Pipeline schema lacks a description to clarify its purpose and usage. This should be documented for API consumers.

 service_account: + description: |- + The service account associated with this pipeline. + Used for authentication and authorization when executing pipeline operations. $ref: '#/components/schemas/ServiceAccount'

---

1460-1461: Add description to service_account field in PipelineCreate schema.

The new service_account field in the PipelineCreate schema lacks a description to clarify its purpose during pipeline creation.

 service_account: + description: |- + The service account to associate with the pipeline. + This is used for authentication and authorization during pipeline creation and operation. $ref: '#/components/schemas/ServiceAccount'

---

1484-1485: Add description to service_account field in PipelineUpdate schema.

The new service_account field in the PipelineUpdate schema lacks a description to clarify its purpose during pipeline updates.

 service_account: + description: |- + The service account to associate with the pipeline. + If provided, updates the service account used for authentication and authorization. $ref: '#/components/schemas/ServiceAccount'

📜 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.

📥 Commits

Reviewing files that changed from the base of the PR and between 25b10f3 and 6eb4b5c.

📒 Files selected for processing (2)

• cloud-controlplane/cloud-controlplane.yaml (2 hunks)
• cloud-dataplane/cloud-dataplane.yaml (8 hunks)

🔇 Additional comments (5)

cloud-controlplane/cloud-controlplane.yaml (2)

2568-2580: Improved description clarity for private_url semantics.

The updated description for ServerlessCluster.DataplaneAPI.private_url now explicitly clarifies that it represents the private URL when private networking is enabled. This is a helpful improvement for API consumers.

---

2616-2626: Minor title capitalization change for schema registry private_url.

The title has been adjusted from "Private URL for the schema registry" to "Private url for the schema registry" (lowercase 'url'). While this is a minor change, ensure this capitalization aligns with naming conventions used elsewhere in the specification for consistency.

Please confirm whether this lowercase 'url' capitalization is intentional and aligns with other similar titles in the spec, or if it should be standardized with uppercase 'URL'.

cloud-dataplane/cloud-dataplane.yaml (3)

215-215: LGTM: ConnectCluster name description clarified.

The description update for ConnectCluster.name is clear and provides useful context for Redpanda Cloud users.

---

3507-3507: LGTM: Parameter descriptions consistently updated.

The parameter descriptions for cluster_name in the secrets endpoints have been clarified with guidance on using "redpanda" for Redpanda Cloud, aligning with similar updates throughout the spec.

Also applies to: 3626-3626

---

1417-1421: Consider whether service_account should be optional or required in Pipeline schemas.

The service_account fields are not listed in the required arrays for Pipeline, PipelineCreate, or PipelineUpdate. Verify this is intentional and aligns with backend implementation. If service accounts become mandatory in the future, these fields should be added to the required lists.

Also applies to: 1467-1470, 1493-1496

[github-actions]

ℹ️ API content change detected:

No structural change, nothing to display.

Powered by Bump.sh

[github-actions]

ℹ️ API content change detected:

No structural change, nothing to display.

Powered by Bump.sh

[github-actions]

ℹ️ API content change detected:

No structural change, nothing to display.

Powered by Bump.sh