docs(proto): enrich API documentation for all service protos#19659
Open
docs(proto): enrich API documentation for all service protos#19659
Conversation
|
Skipping CI for Draft Pull Request. |
3c4886b to
d0cf5c6
Compare
Added human-readable descriptions to RPC methods, request/response fields, and enum values across all 59 gRPC service definitions (48 v1 + 11 v2). Descriptions cover: - What each RPC does and when to use it - Field semantics, formats, and constraints - Enum value meanings - Pagination, filtering, and query parameter usage This brings API description coverage from ~15% to 98% of operations, enabling downstream tooling (OpenAPI spec generation, SDK codegen, API documentation sites) to produce useful output without manual annotation. No behavioral changes — proto comments only affect generated documentation artifacts (swagger/OpenAPI). Partially generated by AI.
d0cf5c6 to
2af9b8c
Compare
Contributor
|
Images are ready for the commit at 0af87e2. To use with deploy scripts, first |
Codecov Report✅ All modified and coverable lines are covered by tests. Additional details and impacted files@@ Coverage Diff @@
## master #19659 +/- ##
=======================================
Coverage 49.37% 49.38%
=======================================
Files 2743 2743
Lines 207037 207037
=======================================
+ Hits 102223 102243 +20
+ Misses 97228 97213 -15
+ Partials 7586 7581 -5
Flags with carried forward coverage won't be shown. Click here to find out more. ☔ View full report in Codecov by Sentry. 🚀 New features to boost your workflow:
|
Regenerated all 57 Swagger JSON files from the enriched proto definitions. Changes are documentation-only — descriptions now appear in the generated Swagger spec for all enriched RPCs, fields, and enums. Generated output from: make proto-generated-srcs Partially generated by AI.
Updated the v1 and v2 Swagger JSON files bundled in the RHEL container image with enriched API descriptions. Partially generated by AI.
Adds scripts/enrich-proto/ with: - run.sh: automated proto enrichment runner - WORKFLOW.md: documents the enrichment process, audit checklist, and regeneration steps These scripts were used to enrich all 59 service proto files and can be reused for future enrichment passes when new services or fields are added. Partially generated by AI.
Add check-rpc-docs.sh to the existing check-service-protos CI gate. The script scans all proto/api/ service protos and fails if any RPC method lacks a documentation comment above it. Also documents 5 RPCs in report_service.proto and virtual_machine_service.proto that were missing comments. Partially generated by AI.
2af9b8c to
0af87e2
Compare
Contributor
Author
|
/test all |
|
@sthadka: The following tests failed, say
Full PR test history. Your PR dashboard. DetailsInstructions for interacting with me using PR comments are available here. If you have questions or suggestions related to my behavior, please file an issue against the kubernetes-sigs/prow repository. I understand the commands that are listed here. |
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
2 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Description
Adds comprehensive documentation comments to all 59+ API service proto files
and introduces a CI check to prevent undocumented RPCs from being merged.
Proto comments flow through code generation into Swagger specs, gRPC stubs,
and downstream OpenAPI docs, enabling Stripe-quality API documentation
renderers (Redocly, Scalar) without maintaining separate doc sources.
What changed:
proto/api/v1/and
proto/api/v2/service protos with descriptions covering purpose, behavior,required fields, side effects, and permission requirements
.swagger.json,.pb.go,_grpc.pb.go)image/rhel/docs/api/)check-rpc-docs.shCI gate that failsmake styleif any RPC lacks adoc comment
scripts/enrich-proto/) for future protodocumentation maintenance
Why proto comments instead of separate docs:
make proto-generated-srcspropagates changes automaticallyAlternative considered: Enriching storage protos as well (as attempted in
PR #15999). Decided against it because storage types are internal implementation
details that should not leak into the public API surface.
User-facing documentation
Testing and quality
Automated testing
CI check
check-rpc-docs.shvalidates that no undocumented RPCs exist.No runtime behavior changes — documentation comments only.
How I validated my change
make proto-generated-srcsto regenerate all downstream artifactsbash tools/check-service-protos/check-rpc-docs.shpasses (exit 0)bash tools/check-service-protos/run.shpasses (exit 0)Partially generated by AI.