search

protobuf-net / protobuf-net.Grpc

GRPC bindings for protobuf-net and grpc-dotnet
Other
846 stars 106 forks source link

Question: Documentation of code-first gRPC services #287

Open vadimdr opened 1 year ago

vadimdr commented 1 year ago

Hi,

We are developing an extensive set of gRPC code-first shared services that need to be documented for the consumers. One way is to have separate documentation explaining the contracts/usage. Still, my goal is to store the documentation with the code itself so that any change to the contract can be documented as part of the same PR.

Regular gRPC services can support either proto file documentation or OpenAPI with gRPC JSON transcoding. Neither of the methods is available for the code-first gRPC services. gRPC JSON transcoding also allows OpenAPI descriptions from the proto comments. Is there a way to support the same capability in code-first gRPC services? To allow moving all the comments from the code to the proto files generated explicitly or through reflection or to support OpenAPI with gRPC JSON transcoding for code-first services by utilizing Api Explorer type annotations.

mgravell commented 1 year ago

A problem there is that comments aren't available to reflection; the best we could do at runtime would be to consider things like [Description("...")]. Comments would be available if we get things to AOT state, but we're a while away from completing that.

vadimdr commented 1 year ago

This is precisely why I was thinking about using annotations for these purposes. ApiExplorer is another way we can follow here to allow metadata annotations and shipped with ASP.Net Core