auto-docs: Update Admin API docs for v25.3.2 #46
Conversation
vbotbuildovich
force-pushed
the
auto-docs/admin-api
branch
from
b1ec203 to
e7bc3e3
Compare
📝 WalkthroughWalkthroughThis PR updates the Redpanda Admin API v2 OpenAPI specification to introduce support for SASL/PLAIN authentication. It adds a new 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 structural change detected: Modified (5)
|
|
ℹ️ 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
Caution
Some comments are outside the diff and can’t be posted inline due to platform limitations.
⚠️ Outside diff range comments (2)
admin/admin-v2.yaml (2)
1152-1161: Potential enum ambiguity:PATTERN_TYPE_PREFIXvsPATTERN_TYPE_PREFIXED.
Having bothPATTERN_TYPE_PREFIXandPATTERN_TYPE_PREFIXEDis easy to misinterpret (are they synonyms, or meaningfully different?). If both are intentional, please add a short description per value (or a note in the enum description) so client authors know which to use.
-->
1882-1892: Potential enum ambiguity:ACL_PATTERN_PREFIXEDvs newACL_PATTERN_PREFIX.
Same concern asPatternType: two “prefix” flavors are unclear without per-value docs. If this is mirroring upstream Kafka semantics or a rename, it’s worth documenting the distinction (or deprecating one) to prevent client misuse.
-->
🧹 Nitpick comments (3)
admin/admin-v2.yaml (3)
506-530: Consider adding a discriminator forAuthenticationConfigurationoneOf(codegen ergonomics).
The wrapper-styleoneOfbranches (plainConfigurationvsscramConfiguration) are valid, but many generators produce nicer models with an explicitdiscriminator(and it also reduces ambiguity during deserialization).
-->
1161-1187: SASL/PLAIN credential schema: tighten docs to avoid accidental secret handling.
passwordis correctlywriteOnly, but the description is very minimal; I’d recommend explicitly stating “never returned” and clarifying whetherusernameis required when settingpassword(currently neither isrequired). This helps client authors avoid partial/invalid updates and avoids any implication secrets might be echoed.
-->
2077-2112: Docs quality: avoid long single-linesummarystrings (rendering/readability).
A fewsummary:lines are now very long and include double spaces, which tends to wrap poorly in rendered docs. Consider keeping summaries short and pushing detail intodescription(which you already expanded).- summary: ListKafkaConnections returns information about the cluster's Kafka connections, collected and ordered across all brokers. + summary: ListKafkaConnections returns information about the cluster's Kafka connections. - summary: This operation returns information about a Shadow Topic on a Shadow Link. A Shadow Topic is a resource created automatically by a Shadow Link. The Shadow Topic 'shadows' a topic on a source cluster, mirroring the data and properties of that topic. + summary: Get information about a Shadow Topic on a Shadow Link. - summary: This operation returns a list of all Shadow Topics on a Shadow Link and their status + summary: List all Shadow Topics on a Shadow Link and their status ``` --> Also applies to: 2256-2293, 2331-2366 </blockquote></details> </blockquote></details> <details> <summary>📜 Review details</summary> **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. <details> <summary>📥 Commits</summary> Reviewing files that changed from the base of the PR and between eecf2775338f2ebede49e36138d9b74592676471 and e7bc3e36ac5db541e36c6d598e40e766ec8a5cb7. </details> <details> <summary>📒 Files selected for processing (1)</summary> * `admin/admin-v2.yaml` (13 hunks) </details> <details> <summary>🧰 Additional context used</summary> <details> <summary>🧠 Learnings (2)</summary> <details> <summary>📓 Common learnings</summary>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.</details> <details> <summary>📚 Learning: 2025-11-26T19:18:28.591Z</summary>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:** - `admin/admin-v2.yaml` </details> </details> </details> <details> <summary>🔇 Additional comments (3)</summary><blockquote> <details> <summary>admin/admin-v2.yaml (3)</summary><blockquote> `1994-2002`: **Generated metadata update looks consistent.** `x-generated-at` and `x-redpanda-core-version: v25.3.2` updates match the PR objective (v25.3.2 regen). --> --- `2004-2074`: **Operation description tweaks look fine.** The updated wording (“returns information…”, “fails over…”) is consistent and clearer; no issues. --> Also applies to: 2185-2218 --- `1161-1187`: **Please verify enum/value additions and `oneOf` shape align with upstream generator output.** Given this file is produced by `doc-tools generate bundle-openapi`, I’d mainly want confirmation that the upstream source (proto/IDL) truly contains `PATTERN_TYPE_PREFIXED` + `ACL_PATTERN_PREFIX` and that codegen consumers handle the `oneOf` structure as intended (or whether a discriminator is supported/expected by the generator). --> Also applies to: 506-530, 1152-1161, 1882-1892 </blockquote></details> </blockquote></details> </details> <!-- This is an auto-generated comment by CodeRabbit for review status -->
This PR adds the latest OpenAPI spec for version v25.3.2 of the Redpanda Admin API: