Skip to content

auto-docs: Update Cloud API spec #23

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
kbatuigas merged 2 commits into from
Oct 3, 2025
Merged

auto-docs: Update Cloud API spec #23

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
c24b238
auto-docs: Update Cloud API spec
vbotbuildovich Sep 30, 2025
406668e
Apply suggestions from code review
kbatuigas Oct 3, 2025
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
30 changes: 25 additions & 5 deletions cloud-controlplane/cloud-controlplane.yaml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -107,7 +107,8 @@ components:
type: string
type: array
connect_console:
description: Whether Console is connected in Redpanda AWS Private Link Service.
description: Whether Console is connected in Redpanda AWS Private Link Service. The default is true if not set.
nullable: true
type: boolean
enabled:
description: Whether Redpanda AWS Private Link Endpoint Service is enabled.
Expand Down Expand Up @@ -221,7 +222,8 @@ components:
type: string
type: array
connect_console:
description: Whether Console is connected in Redpanda Azure Private Link Service.
description: Whether Console is connected in Redpanda Azure Private Link Service. The default is true if not set.
nullable: true
type: boolean
enabled:
description: Enabled controls if Azure Private Link Endpoint Service is enabled.
Expand Down Expand Up @@ -265,6 +267,8 @@ components:
Cluster:
description: Resource describing a Cluster.
properties:
api_gateway_access:
$ref: '#/components/schemas/NetworkAccessMode'
aws_private_link:
$ref: '#/components/schemas/AWSPrivateLink'
azure_private_link:
Expand Down Expand Up @@ -504,6 +508,8 @@ components:
ClusterCreate:
description: Resource describing a Create Cluster.
properties:
api_gateway_access:
$ref: '#/components/schemas/NetworkAccessMode'
aws_private_link:
$ref: '#/components/schemas/AWSPrivateLinkSpec'
azure_private_link:
Expand Down Expand Up @@ -646,6 +652,8 @@ components:
ClusterUpdate:
description: Resource describing an Update Cluster.
properties:
api_gateway_access:
$ref: '#/components/schemas/NetworkAccessMode'
aws_private_link:
$ref: '#/components/schemas/AWSPrivateLinkSpec'
azure_private_link:
Expand Down Expand Up @@ -1944,6 +1952,12 @@ components:
- STATE_DELETING
- STATE_FAILED
type: string
NetworkAccessMode:
description: Network access mode for an endpoint.
enum:
- NETWORK_ACCESS_MODE_PRIVATE
- NETWORK_ACCESS_MODE_PUBLIC
type: string
Comment on lines +1955 to +1960
Copy link

@coderabbitai coderabbitai bot Sep 19, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

⚠️ Potential issue

Enum/examples mismatch: add UNSPECIFIED or fix examples

Examples use NETWORK_ACCESS_MODE_UNSPECIFIED but the enum omits it. Add UNSPECIFIED to avoid invalid examples or update examples to a valid value.

Apply one of:
Option A (preferred: add enum value)

 NetworkAccessMode:
   description: Network access mode for an endpoint.
   enum:
+    - NETWORK_ACCESS_MODE_UNSPECIFIED
     - NETWORK_ACCESS_MODE_PRIVATE
     - NETWORK_ACCESS_MODE_PUBLIC
   type: string
📝 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.

Suggested change
NetworkAccessMode:
description: Network access mode for an endpoint.
enum:
- NETWORK_ACCESS_MODE_PRIVATE
- NETWORK_ACCESS_MODE_PUBLIC
type: string
NetworkAccessMode:
description: Network access mode for an endpoint.
enum:
- NETWORK_ACCESS_MODE_UNSPECIFIED
- NETWORK_ACCESS_MODE_PRIVATE
- NETWORK_ACCESS_MODE_PUBLIC
type: string
🤖 Prompt for AI Agents 
In cloud-controlplane/cloud-controlplane.yaml around lines 1953 to 1958, the
OpenAPI enum lists NETWORK_ACCESS_MODE_PRIVATE and NETWORK_ACCESS_MODE_PUBLIC
but examples reference NETWORK_ACCESS_MODE_UNSPECIFIED, causing invalid
examples; add NETWORK_ACCESS_MODE_UNSPECIFIED to the enum definition (preferably
as the first value) so examples validate, and ensure any schema
default/description reflects the new UNSPECIFIED value; alternatively, update
examples to use one of the existing enum values if you choose not to add
UNSPECIFIED.

NetworkCreate:
description: Redpanda Cloud network properties.
properties:
Expand Down Expand Up @@ -3258,7 +3272,7 @@ components:
x-client-id: dQjapNIAHhF7EQqQToRla3yEII9sUSap
type: oauth2
info:
description: Use the Control Plane API to manage resources in your Redpanda Cloud organization such as clusters and networks.
description: The Redpanda Cloud Control Plane API allows programmatic management of Redpanda Cloud resources including clusters, networks, and resource groups.
title: Redpanda Cloud Control Plane API
version: v1
openapi: 3.0.3
Expand Down Expand Up @@ -3316,7 +3330,8 @@ paths:
application/json:
example:
clusters:
- cloud_provider: CLOUD_PROVIDER_GCP
- api_gateway_access: NETWORK_ACCESS_MODE_UNSPECIFIED
Copy link
Contributor

@kbatuigas kbatuigas Oct 3, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Will try adding overlays to target and use a public value

cloud_provider: CLOUD_PROVIDER_GCP
cloud_provider_tags: {}
cloud_storage: null
cluster_configuration: null
Expand Down Expand Up @@ -3500,6 +3515,8 @@ paths:
schema:
description: Resource describing an Update Cluster.
properties:
api_gateway_access:
$ref: '#/components/schemas/NetworkAccessMode'
aws_private_link:
$ref: '#/components/schemas/AWSPrivateLinkSpec'
azure_private_link:
Expand Down Expand Up @@ -3651,6 +3668,7 @@ paths:
application/json:
example:
cluster:
api_gateway_access: NETWORK_ACCESS_MODE_UNSPECIFIED
cloud_provider: CLOUD_PROVIDER_GCP
cloud_provider_tags: {}
cloud_storage: null
Expand Down Expand Up @@ -4049,6 +4067,7 @@ paths:
response:
'@type': type.googleapis.com/redpanda.api.controlplane.v1.CreateClusterResponse
cluster:
api_gateway_access: NETWORK_ACCESS_MODE_UNSPECIFIED
cloud_provider: CLOUD_PROVIDER_GCP
cloud_provider_tags: {}
cloud_storage: null
Expand Down Expand Up @@ -4174,6 +4193,7 @@ paths:
response:
'@type': type.googleapis.com/redpanda.api.controlplane.v1.CreateClusterResponse
cluster:
api_gateway_access: NETWORK_ACCESS_MODE_UNSPECIFIED
cloud_provider: CLOUD_PROVIDER_GCP
cloud_provider_tags: {}
cloud_storage: null
Expand Down Expand Up @@ -5690,7 +5710,7 @@ tags:
name: Resource Groups
- description: Manage [Redpanda Serverless](https://docs.redpanda.com/redpanda-cloud/get-started/cloud-overview/#redpanda-cloud-cluster-types) clusters. For detailed steps, see [Use the Control Plane API with Serverless](https://docs.redpanda.com/redpanda-cloud/manage/api/cloud-serverless-controlplane-api/).
name: Serverless Clusters
- description: Manage Redpanda Serverless private links.
- description: Manage Redpanda Serverless Private Links. For detailed steps and information, see [Use the Control Plane API](https://docs.redpanda.com/redpanda-cloud/manage/api/controlplane/).
name: Serverless Private Links
- description: See available Redpanda Serverless regions.
name: Serverless Regions
Expand Down
7 changes: 6 additions & 1 deletion cloud-dataplane/cloud-dataplane.yaml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -1792,6 +1792,8 @@ components:
enum:
- SCOPE_REDPANDA_CONNECT
- SCOPE_REDPANDA_CLUSTER
- SCOPE_MCP_SERVER
- SCOPE_AI_AGENT
type: string
Secret:
description: Defines the secret resource.
Expand Down Expand Up @@ -2227,7 +2229,6 @@ components:
info:
title: Redpanda Cloud Data Plane API
version: v1
description: Use the Data Plane API to manage topics, ACLs, and connectors within each cluster.
openapi: 3.0.3
paths:
/v1/acls:
Expand Down Expand Up @@ -3516,6 +3517,8 @@ paths:
enum:
- SCOPE_REDPANDA_CONNECT
- SCOPE_REDPANDA_CLUSTER
- SCOPE_MCP_SERVER
- SCOPE_AI_AGENT
type: string
type: array
- description: |-
Expand Down Expand Up @@ -4806,6 +4809,8 @@ paths:
enum:
- SCOPE_REDPANDA_CONNECT
- SCOPE_REDPANDA_CLUSTER
- SCOPE_MCP_SERVER
- SCOPE_AI_AGENT
type: string
type: array
- description: |-
Expand Down