search

protocolbuffers / protobuf

Protocol Buffers - Google's data interchange format
http://protobuf.dev
Other
64.98k stars 15.41k forks source link

UML Class Diagrams #6043

Open Cory-Kramer opened 5 years ago

Cory-Kramer commented 5 years ago

What language does this apply to? If it's a proto syntax change, is it for proto2 or proto3? proto3 If it's about generated code change, what programming language? any

Describe the problem you are trying to solve.

It would be very useful to generate class diagrams based on protobuf message definitions, including the members/fields of each class, as well as the class relationships.

Describe the solution you'd like

A script or command-line utility to output images (e.g. png) or something like GraphViz files with the generated UML diagrams.

Describe alternatives you've considered

I've looked into protoc-gen-uml and protobuf2uml but both tools lack useful documentation and neither are actively maintained.

kinow commented 5 years ago

Spent some time today looking for a way to create this diagram, until I decided to search here for previous issues.

My use case, is that another developer created the .proto file, and quickly plotting a simple class diagram would give me a good initial understanding. Plus, it would be useful for our documentation as well. Even better if later there is a way to call it programmatically in Python too, so that we can hook it up in our setuptools + sphinx documentation.

Also tried to create a class diagram in PyCharm. But PyCharm's protobuf support does not offer the option to create the diagram from the .proto file, and it does not produce a diagram if you instead point to the generated _pb2.py file.

Thanks

ghost commented 5 years ago

This is a nice feature request, but we don't have time to build this. Perhaps someone in the community would step up and improve on the existing UML tool / build better alternatives?

kinow commented 5 years ago

I tried running tssp/protoc-gen-uml, but it is written in Scala. I wrote Java most of my life, but working with Python now, I find it easier to use and contribute to Python/Go/Rust/Shell small libs or tools.

And I couldn't get https://github.com/vak/protobuf2uml, which is Python, to work. It uses Antlr from what I understood, to parse the .proto file.

But I thought a simpler approach would be to use the introspection/reflection available in protobuf in Python. Given a compiled Python module, added in the PYTHONPATH, then a small Python script could read the fields with just protobuf code... then use GraphViz/dot to render a UML diagram.

So created a small utility that successfully rendered the code in our project. In case others find it useful too: https://github.com/kinow/protobuf-uml-diagram/

Cheers Bruno

jimmywan commented 5 years ago

Also couldn't get https://github.com/vak/protobuf2uml to work.

Thx @kinow . I was able to wrangle https://github.com/kinow/protobuf-uml-diagram/ into almost doing what I wanted, but ran into a few minor issues. Will discuss in your repo and maybe we can figure out if what I have is reasonable to merge back in at some point. I had to hack it up pretty badly to support my use case.