How to Generate Protobuf documentation?

Question

Does anyone know of a good tool to generate Google Protobuf documentation using the .proto source files?

The documentation generated from the below source is excellent. https://github.com/pseudomuto/protoc-gen-doc

But, being a java developer, I am not sure how we can use the above project in my maven - java project.

Any help on this is appreciated

Answer 1

One way to use the protoc-gen-doc project in your Maven-based Java project is to use the Maven Protoc Plugin along with the protoc-gen-doc binary.

Here are the steps you can follow:

1. Download the protoc-gen-doc binary from the project's GitHub releases page and extract it to a directory in your project.

2. install it mvn install:install-file -DgroupId=org.pseudomuto -DartifactId=protoc-gen-doc -Dversion=1.5.0 -Dclassifier=linux-x86_64 -Dpackaging=exe -Dfile=protoc-gen-doc file path

3. Add the Maven Protoc Plugin to your pom.xml file as a build plugin, like this:

    <build>
        <plugins>
            <plugin>
                <groupId>org.xolstice.maven.plugins</groupId>
                <artifactId>protobuf-maven-plugin</artifactId>
                <version>0.6.1</version>
                <executions>
                    <execution>
                        <goals>
                            <goal>compile</goal>
                            <goal>test-compile</goal>
                        </goals>
                    </execution>
                </executions>
                <configuration>
                    <protocArtifact>com.google.protobuf:protoc:3.17.3:exe:${os.detected.classifier}</protocArtifact>
                    <pluginId>protoc-gen-doc</pluginId>
                    <pluginArtifact>org.pseudomuto:protoc-gen-doc:1.5.0:exe:${os.detected.classifier}</pluginArtifact>
                    <pluginParameters>
                        <param>mode=html</param>
                        <param>include_imports</param>
                    </pluginParameters>
                </configuration>
            </plugin>
        </plugins>
    </build>
   

This configures the protobuf-maven-plugin to use the protoc-gen-doc binary as a plugin for generating HTML documentation from the .proto files.

4. Run the protobuf:compile goal to generate the documentation:

mvn protobuf:compile

This will generate the documentation in the target/docs/ directory.

Note: You may need to update the version numbers of the protobuf-maven-plugin, com.google.protobuf:protoc and org.pseudomuto:protoc-gen-doc dependencies to match the latest versions.