gRPC is great when it goes to communication between services. It has many built-in mechanisms to speed up the development process, like auto-generating SDK or streaming support. Seems to be the perfect choice for building your API, right? But in the real world, there are not many public gRPC APIs. REST is still the king. Most gRPC backends expose only the REST API.

The main problem is that gRPC is hard. It is hard to start, it is hard to play with, and even hard to debug. The typical solution for that is to use the REST-to-gRPC translation proxy, like grpc-gateway. That’s not a perfect solution because it complicates the architecture, increases the latency and the maintenance costs.

In this post, I’ll compare a few gRPC documentation generators that can help you mitigate those problems. Let’s create a truly gRPC API documentation!

gRPC-docs

gRPC Docs is an open-source project. The main goal is to deliver a Swagger-UI-like experience for gRPC API. It might be self-hosted or styled in any manner you like. Check the demo.

Setup self-served (4 minutes)

1. Install protoc-gen-doc with go get -u github.com/pseudomuto/protoc-gen-doc/cmd/protoc-gen-doc or with docker.
2. Generate the JSON API description with command protoc --doc_out=./ --doc_opt=json,description.json -I your-proto-root your-proto-files
3. Inside your react project (if you don’t have one, clone the repository git clone https://github.com/gendocu-com/grpc-docs and go to example directory) add the library - npm install --save grpc-docs.
4. Copy the description.json file from the 2nd step to the public directory in the project
5. Instantiate the grpc-docs widget with the path to the description.json file, e.g., for a file located in public/example-descriptors/library-app.json:

import React from 'react'

import { GRPCSelfGeneratedAPIReference } from 'grpc-docs'
import 'grpc-docs/dist/index.css'

const App = () => {
    return <GRPCSelfGeneratedAPIReference file='/example-descriptors/library-app.json' scheme='/example-descriptors/library-app-apispec.yaml' />
}

export default App

Summary

gRPC Developer Portal (GenDocu Cloud)

GenDocu Cloud is CI/CD solution to build and deliver the gRPC. It automatically subscribes to all the new commits via GitHub and rebuilds the documentation and SDKs. It also generates the SDKs and code-snippets for six programming languages. It also handles the gRPC Web SDK generation. It is possible to define the example values for message structures and authentication schemes. You can also call the endpoints from documentation like in Swagger UI. Check full documentation demo or API Reference demo to explore all the features.

Setup (1 minute)

It’s cloud solution, so no additional setup is required.

1. Login to GenDocu Cloud
2. Create a new project - select the gRPC source directly from your GitHub repository.
3. Visit the result documentation page

Summary

Buf

One of the most popular gRPC tools is the buf CLI - it extends the features known from prototool. The Buf company has created a superb tool and integrated it with its own API Schema Registry. Every schema has its documentation - an example can be found here, here or here.

Setup (4 minutes)

1. Install the Buf CLI
2. Authorize the Buf CLI with buf registry login
3. Create a repository on the buf.build webpage
4. Create a configuration file buf config init and reference the repository - the buf.build/
5. Use command build push to create a scheme in the Buf’s registry.

Summary

Buf is not a documentation tool. Nevertheless, it provides decent documentation for your gRPC API.

protoc-gen-doc

There is also a great, open-source project - protoc-gen-doc. It is free and generates the documentation in Markdown, HTML, or JSON. Sadly, it is a protobuf documentation tool - not gRPC. It generates the description of the protobuf structure without even mentioning the gRPC services and methods.

Setup (2 minutes)

1. Install it with go get -u github.com/pseudomuto/protoc-gen-doc/cmd/protoc-gen-doc. It is also possible to use dockerized version - more here.
2. Invoke the plugin protoc --doc-opt=html,docs.html <your-protos>
3. Open docs.html file

Summary

It is a good starter for the project - it can be easily adjusted/replaced.

Comparison summary

protoc-gen-doc is fine for internal documentation - it is easiest to set up, but it doesn’t generate the gRPC documentation. You have to host it on your own. It is the only self-hosted option.

GenDocu Cloud is the best to start with as it provides CI/CD out of the box - you can set it up in a minute and requires no maintenance. Great for public and private gRPC API documentation.

Buf is the only GenDocu alternative when it goes to public, hosted, gRPC API documentation.

If you find anything missing, please let us know at support[at]gendocu.com