Improve descriptions for OpenAPI (backport)#29040
Conversation
kbatuigas
requested review from
a team,
michael-redpanda,
r-vasquez and
rockwotj
as code owners
|
|
|
The latest Buf updates on your PR. Results from workflow Buf CI / validate (pull_request).
|
There was a problem hiding this comment.
Pull request overview
This PR backports OpenAPI documentation improvements from the API docs repository to the source proto files. The changes ensure consistency in how method summaries and descriptions render in the public documentation. The updates primarily focus on adding missing method descriptions in the ShadowLinkService and standardizing description formatting across multiple services.
Key Changes
- Added method descriptions to ShadowLinkService RPCs (CreateShadowLink, DeleteShadowLink, GetShadowLink, ListShadowLinks, UpdateShadowLink)
- Standardized method description formatting in BrokerService and ClusterService to use "Returns" instead of verbose phrasing
- Updated comment formatting for GetShadowTopic and ListShadowTopics methods
Reviewed changes
Copilot reviewed 9 out of 9 changed files in this pull request and generated 1 comment.
Show a summary per file
| File | Description |
|---|---|
| proto/redpanda/core/admin/v2/shadow_link.proto | Added missing method descriptions and improved existing ones for all ShadowLinkService RPCs |
| proto/redpanda/core/admin/v2/broker.proto | Standardized method descriptions to use "Returns" prefix |
| proto/redpanda/core/admin/v2/cluster.proto | Standardized method description to use "Returns" prefix |
| proto/redpanda/core/pbgen/comments.pb.go | New generated file consolidating comments from proto files |
| src/go/rpk/gen/protocomments/admin/v2/comments.pb.go | Generated file updated with new and improved method descriptions |
| src/go/rpk/gen/protocomments/common/v1/comments.pb.go | Generated file updated with TopicPartition comments |
| tests/rptest/clients/admin/proto/redpanda/core/admin/v2/init.pyi | Removed unused import statement |
| tests/rptest/clients/admin/proto/redpanda/core/admin/v2/shadow_link_pb2.py | Generated Python file updated with proto changes |
| tests/rptest/clients/admin/proto/redpanda/core/common/v1/tls_pb2.py | Generated Python file updated with proto changes |
| from . import cluster_pb2 | ||
| from . import internal | ||
| from . import kafka_connections_pb2 | ||
| from . import shadow_link_pb2 |
There was a problem hiding this comment.
The removal of the 'internal' import should be verified. If this module exists and is used elsewhere in the test suite, removing this import could break functionality. Only remove if the module truly doesn't exist or is genuinely unused throughout the codebase.
| from . import shadow_link_pb2 |
kbatuigas
force-pushed
the
kb/docs/proto/patch-descriptions
branch
from
d28a460 to
48433d8
Compare
michael-redpanda
left a comment
michael-redpanda
left a comment
There was a problem hiding this comment.
Changes look good - I would squash the two commits that have the comment changes into a single commit and then do one more follow on commit to update the autogenerated files
rockwotj
force-pushed
the
kb/docs/proto/patch-descriptions
branch
from
7506763 to
4c7304f
Compare
rockwotj
left a comment
rockwotj
left a comment
There was a problem hiding this comment.
Rebased and squashed commits
rockwotj
force-pushed
the
kb/docs/proto/patch-descriptions
branch
from
4c7304f to
3bc6fde
Compare
|
I think this broke CI: https://buildkite.com/redpanda/redpanda/builds/78166#019b3390-35cf-40df-aeb9-36c4fc8135f6 |
|
Yes it did, sorry I think it's a bug in which checks happen. I can fix tonight |
|
/backport v25.3.x |
The OpenAPI spec used by our docs build was patched to ensure consistency in how method summaries and descriptions render in our public docs: https://docs.redpanda.com/api/doc/admin/v2/
This PR backports those fixes to the source protos (including adding missing method descriptions in ShadowLinkService)
Backports Required
Release Notes