auto-docs: Update Admin API docs for v25.3.1 #36
Conversation
📝 WalkthroughWalkthroughThe pull request updates the OpenAPI specification file Estimated code review effort🎯 2 (Simple) | ⏱️ ~10 minutes
Possibly related PRs
Suggested reviewers
Pre-merge checks and finishing touches✅ Passed checks (3 passed)
✨ Finishing touches🧪 Generate unit tests (beta)
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 content change detected: No structural change, nothing to display.
|
|
ℹ️ API content change detected: No structural change, nothing to display.
|
![coderabbitai[bot]](https://avatars.githubusercontent.com/in/347564?s=60&v=4){kind=small}
There was a problem hiding this comment.
Actionable comments posted: 0
🧹 Nitpick comments (2)
admin/admin-v2.yaml (2)
2040-2073: Minor formatting inconsistency in ListKafkaConnections summary.The description uses a line break between "cluster's Kafka" and "connections", but the summary converts this to two consecutive spaces ("Kafka connections"). While semantically equivalent, this creates a minor formatting inconsistency in the OpenAPI spec.
Given this is an auto-generated file, this may be expected YAML formatting behavior. If consistency is desired across the spec, consider normalizing multi-line summaries to use consistent spacing or hyphenation.
2294-2327: ListShadowTopics summary has line-break-to-spaces conversion like ListKafkaConnections.Similar to the ListKafkaConnections endpoint, the description's line break ("Shadow Link and\n their status") is converted to double spaces in the summary ("Shadow Link and their status"). This is consistent with the auto-generation tool's behavior but creates a minor stylistic deviation from typical summary formatting.
📜 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 (1)
admin/admin-v2.yaml(10 hunks)
🔇 Additional comments (3)
admin/admin-v2.yaml (3)
1961-1961: Version metadata updated correctly for v25.3.1 release.The
x-generated-atandx-redpanda-core-versionfields have been updated to reflect the current specification version. These are appropriate for an auto-generated spec update.Also applies to: 1963-1963
1968-1999: BrokerService endpoints now include required Connect headers and updated documentation.Both
GetBrokerandListBrokersendpoints now includeConnect-Protocol-Version(required) andConnect-Timeout-Msheader parameters, with clear operation descriptions and summaries. The documentation consistently describes what each endpoint returns.Also applies to: 2004-2035
2076-2364: ShadowLinkService endpoints: consistent header additions; some endpoints lack descriptions.All ShadowLinkService endpoints now include the required Connect headers. However, there is an inconsistent pattern: while
GetShadowTopicandListShadowTopicsinclude expanded descriptions, endpoints likeCreateShadowLink,DeleteShadowLink,GetShadowLink,ListShadowLinks, andUpdateShadowLinkonly have summaries without descriptions.This pattern aligns with the auto-generation output, where verbose operations document their behavior while shorter operations rely on the summary alone. No functional issues are present, but this is worth noting if manual documentation review is needed.
This PR adds the latest OpenAPI spec for version v25.3.1 of the Redpanda Admin API: