We are excited to share an update to the Generated Documentation feature within the BSR, which now includes support for most built-in Protobuf options. 🎉
A major feature provided by the Buf Schema Registry (BSR) is automatic documentation generation for Protobuf APIs. Documentation is a fantastic developer productivity tool that can be applied by all levels of software engineers during the development process. Good documentation makes a major impact, but it can become a maintenance headache when decoupled from code. Therein lies the beauty of generated documentation!
When a module is pushed to the BSR, we automatically generate comprehensive documentation for that module and display it in the recently redesigned BSR interface, making it easily discoverable for consumers. Visit our earlier blog post for more details on how to document APIs in Protobuf source code.
Protobuf options are annotations that can be added to elements in Protobuf source files to control various aspects of how they are handled - for example, changing how data is serialized, marking types or fields as deprecated, and aliasing enum cases. One can learn more about how options work in the Protobuf Language Guide.
BSR Generated Documentation now supports a selected list of Protobuf options to relay important information to consumers. At this time, we have limited the rendering of options to the list of supported options below:
Message options
deprecatedField options
deprecatedpackedctypejstypeEnum options
allow_aliasdeprecatedEnumValue options
deprecatedService options
deprecatedMethod options
deprecatedidempotency_level
The most notable addition to BSR Generated Documentation is the rendering of the deprecated option. This clearly indicates which elements are deprecated in both the index and the element definitions. Implicit deprecation, where all nested elements inside of a deprecated element become deprecated, is automatically handled by the generation as well.
As an example, check out the generated documentation for the google.api.expr.v1alpha1 package in the buf.build/googleapis/googleapis module:
Other built-in options are rendered inline with the same source code style as shown above with the Explain message. Please note that custom options are not included in BSR Generated Documentation, only the selected list of built-in options are supported at this time.
We’re excited for you to try out the new BSR Generated Documentation, available now! You can take advantage of the new functionality by pushing a module to the BSR. If you haven’t yet pushed your first module to the BSR, you can read more about modules or walk through the Buf tour. For any questions or concerns, don't hesitate to reach out to us on Slack - we'd love to hear from you!
