Proto Gen MD Diagrams

This utility package is a compiled Go program that reads a protobuf source directory and generates Mermaid Diagrams in .md files in each directory, or the output directory with the given tree structure.

NOTE: Only Proto 3 syntax is supported.

This utility was created to ease documentation generation of complex Protobuf libraries to visualize models and services described in a Protocol buffers.

If you find this useful, awesome! If you find a bug, please contribute a patch, or open a bug. Please follow the Contributing guidelines.

Test Input and Output

Build and test

Using Native Go

go build && go test ./...
./proto-gen-md-diagrams -d ./pkg/proto/data/test/

Using Bazel

Since Bazel is CI/CD workflow program it compiles for all targets.

bazel build //... && bazel test //...

# Linux 
bazel-bin/proto-gen-md-diagrams-linux-x86_64

# OS X X64
proto-gen-md-diagrams-osx-x86_64

# OS X Apple Silicon
bazel-bin/proto-gen-md-diagrams-osx-arm64

# Windows
bazel-bin/proto-gen-md-diagrams-win-x86_64

Building

Go Lang

cd proto-gen-md-diagrams
// Build
go build && go test ./...

Use and Options

./proto-gen-md-diagrams -h

Usage of ./proto-gen-md-diagrams:
  -d string
        The directoryFlag to read. (default ".")
  -debugFlag
        Enable debugging
  -o string
        Specifies the outputFlag directoryFlag, if not specified, the processor will write markdown in the proto directories. (default ".")
  -r    Read recursively. (default true)
  -v    Enable Visualization (default true)
  -w    Enable writing output (default true)
  -md   Enable pure MD output (default false)

./proto-gen-md-diagrams -d test/protos

Quick Example

Protobuf Input

// A physical location that can be described with either an address
// or a set of geo coordinates.
message PhysicalLocation {
  // A postal address for the physical location.
  message Address {
    // Address type is used to identify the type of address.
    enum AddressType {
      RESIDENTIAL = 0; // A residential address
      BUSINESS = 1; // A business address
    }
    // First line of the address
    string line1 = 1;
    // Second line of the address
    string line2 = 2;
    // Third line of the address
    string line3 = 3;
    // The city or township
    string city = 4;
    // The state or province
    string state = 5;
    // The postal code
    string zipcode = 6;
    // The type of address
    AddressType type = 7;
    // Reserved for future use
    reserved 8 to 20;
  }
  // The timestamp the record was created
  google.protobuf.Timestamp created = 1;
  // The mailing address of the location
  Address address = 2;
  // Longitude degrees
  int32 longitude_degrees = 3 [json_name = 'lng_d'];
  // Longitude Minutes
  int32 longitude_minutes = 4 [json_name = 'lng_m'];
  // Longitude Seconds
  int32 longitude_seconds = 5 [json_name = 'lng_s'];
  // Longitude Degrees
  int32 latitude_degrees = 6  [json_name = 'lat_d'];
  // Latitude Minutes
  int32 latitude_minutes = 7  [json_name = 'lat_m'];
  // Latitude Seconds
  int32 latitude_seconds = 8  [json_name = 'lat_s'];
  // Latitude Direction Code
  string latitude_direction_code = 9  [json_name = 'lat_dir_code'];
  // Altitude in Meters
  double altitude_meters = 10  [json_name = 'alt_m'];
  // Additional Meta Data
  map<string, string> meta = 11;
  // Names for the location
  repeated string names = 12 [json_name = 'names'];
}

Markdown Output

Diagram

classDiagram
direction LR

%% A physical location that can be described with either an address or a set of geo coordinates.
class PhysicalLocation {
  + Address address
  + double altitude_meters
  + google.protobuf.Timestamp created
  + int32 latitude_degrees
  + string latitude_direction_code
  + int32 latitude_minutes
  + int32 latitude_seconds
  + int32 longitude_degrees
  + int32 longitude_minutes
  + int32 longitude_seconds
  + Map<string,  string> meta
  + List<string> names
}
PhysicalLocation --> `Address`
PhysicalLocation --> `google.protobuf.Timestamp`
PhysicalLocation --o `Address`

%% A postal address for the physical location.
class Address {
  + string line1
  + string line2
  + string line3
  + string city
  + string state
  + string zipcode
  + AddressType type
}
Address --> `AddressType`
Address --o `AddressType`
%% Address type is used to identify the type of address.
class AddressType{
  <<enumeration>>
  RESIDENTIAL
  BUSINESS
}

Description

A physical location that can be described with either an address or a set of geo coordinates.