auto-docs: Update Cloud API spec

[vbotbuildovich]

This PR updates the OpenAPI spec file for the Cloud API.
Triggered by commit: 135b1ce9d809820ac0e9f820705395c1ec90b260

[coderabbitai]

📝 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 states "This PR updates the OpenAPI spec file for the Cloud API" and references a triggering commit. This description is directly related to the changeset, which contains updates to OpenAPI specification files (cloud-controlplane.yaml and cloud-dataplane.yaml) with schema modifications, new entity definitions, and field description updates. The description accurately captures the nature of the changes without being off-topic or completely unrelated to the work performed. While the description lacks specifics about individual changes, the evaluation criteria explicitly states that level of detail is not important for a passing assessment.

✨ Finishing touches

• 📝 Generate docstrings

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Post copyable unit tests in a comment
• Commit unit tests in branch update-branch-api

---

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

[github-actions]

🚨 Breaking API change detected:

Added (1)

• PATCH /v1/serverless/clusters/{id}

Modified (2)

• GET /v1/serverless/clusters
  • Response modified: 200
    • Content type modified: application/json
      • Property modified: serverless_clusters
        • [Breaking] Properties removed: network, private_link
          • Removing a resource is always breaking unless it was deprecated before [Breaking]
        • Properties added: networking_config, private_link_id
  • Query parameter added: filter.private_link_id
• GET /v1/serverless/clusters/{id}
  • Response modified: 200
    • Content type modified: application/json
      • [Breaking] Properties removed: network, private_link
        • Removing a resource is always breaking unless it was deprecated before [Breaking]
      • Properties added: networking_config, private_link_id

Preview documentation

Powered by Bump.sh

[github-actions]

🤖 API structural change detected:

Modified (8)

• GET /v1/redpanda-connect/pipelines
  • Response modified: 200
    • Content type modified: application/json
      • Property modified: pipelines
        • Property added: service_account
• GET /v1/redpanda-connect/pipelines-by-secrets
  • Response modified: 200
    • Content type modified: application/json
      • Property modified: pipelines_for_secret
        • Property modified: pipelines
• GET /v1/redpanda-connect/pipelines-for-secret
  • Response modified: 200
    • Content type modified: application/json
      • Property modified: pipelines_for_secret
        • Property modified: pipelines
• GET /v1/redpanda-connect/pipelines/{id}
  • Response modified: 200
    • Content type modified: application/json
      • Property added: service_account
• POST /v1/redpanda-connect/pipelines
  • Content type modified: application/json
    • Property added: service_account
  • Response modified: 201
    • Content type modified: application/json
      • Property added: service_account
• PUT /v1/redpanda-connect/pipelines/{id}
  • Content type modified: application/json
    • Property added: service_account
  • Response modified: 200
    • Content type modified: application/json
      • Property added: service_account
• PUT /v1/redpanda-connect/pipelines/{id}/start
  • Response modified: 200
    • Content type modified: application/json
      • Property added: service_account
• PUT /v1/redpanda-connect/pipelines/{id}/stop
  • Response modified: 200
    • Content type modified: application/json
      • Property added: service_account

Preview documentation

Powered by Bump.sh

[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