// css

Contents

gRPC Documentation Generators - tools comparison


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. You can use it for free with your own CI/CD or connect it with GenDocu Cloud CI/CD.

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

Setup with gRPC CI/CD (3 minutes)

  1. Create a project to build your gRPC API on GenDocu Cloud
  2. Add the Javascript library to your existing documentation project with command npm install --save grpc-docs or use the example project - git clone https://github.com/gendocu-com/grpc-docs and then go to example directory.
  3. Replace the default project with your project name and organization created in 1st step:
import React from 'react'

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

const App = () => {
  return <GRPCGenDocuAPIReference project='LibraryApp' organization='gendocu' />
}

export default App

Summary

Pros:

  • Free and open-sourced
  • Quick setup - no tools or config files are required to start
  • Easy to override/create own style
  • Easy to embed within existing documentation tool
  • Ready-to-copy gRPC Curl queries with the setup steps - similar to curl command for REST API

Cons:

  • Try it out only with the GenDocu Cloud project (gRPC is not supported directly in browsers)
  • For code-snippets and SDKs requires GenDocu Cloud project
  • No built-in support for private documentation - the only way is to restrict it directly on your hosting

gRPC Developer Portal (GenDocu Cloud)

/images/grpc-docs-comparision/library-app-screenshot-gendocu.png

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.

Setup (2 minutes)

You can also use the demo documentation to explore all the features.

  1. Login to GenDocu Cloud
  2. Create a new documentation
  3. Pick the SDK’s programming languages
  4. Choose the SDK libraries storage - own GitHub repository or GenDocu hosted
  5. Select the protobuf Git repository
  6. Name your documentation
  7. Visit the documentation page https://doc.gendocu.com/<your-nickname>/api/<documentation-name>

Summary

Pros:

  • Free for individuals and small teams
  • Quick setup - no tools or config files are required to start
  • Integrated CI/CD for gRPC with linter
  • Generates the SDK for 4 gRPC technologies (Golang, Java, C#, Python) and 2 gRPC Web (Javascript, Typescript)
  • Generates the code snippets for each endpoint
  • Try it out
  • RBAC support
  • Embeddable as an HTML widget
  • You can style the documentation with an open-source project grpc-docs

Cons:

  • Paid for medium and big companies
  • No self-hosted option
  • Supports only GitHub
  • Requires to provide the raw Protobuf files from repository - can’t use only descriptor like in Google Endpoints

Google Endpoints (Google Smart Docs)

/images/grpc-docs-comparision/library-app-screenshot-google-cloud.png

Google Cloud is heavily investing in the gRPC. In this article, we described their Serverless gRPC functions. Google Smart Docs is a free tool to create your API documentation. It can generate the documentation for both REST and gRPC APIs. Moreover, it is free! Here you can find demo documentation. The Smart Docs are an interesting alternative for Swagger UI, but sadly gRPC support is very limited. It generates the gRPC documentation with type descriptions and even the API Authentication schemes but still lacks features like “Try it out” or example values.

Setup (10 minutes)

Before proceeding, you have to install the Cloud SDK.

  1. Go to Google Cloud Endpoints and click “Create Portal”. It might take a few minutes to create one - in our case took 7 minutes.
  2. Generate the descriptor set for your proto API. Use command: protoc --proto_path=. --include_imports --include_source_info --descriptor_set_out=api_descriptor.pb
  3. Create an API specification file.
  4. Upload the files: gcloud endpoints services deploy api_descriptor.pb api_config.yaml
  5. Visit your documentation portal.

Summary

Google Endpoints is an easy solution if you want private-only documentation and already have configured CI/CD.

Pros:

  • Free to use
  • You can style the documentation with custom CSS
  • RBAC support
  • You can define the authentication scheme - it is mentioned in the footer

Cons:

  • Exposing the documentation to the public is hard - we haven’t found any information about it
  • Does not generate the SDK or code-snippets for programming languages
  • Requires Cloud SDK to use - for Google Cloud users, that’s not a big deal
  • No “Try it out” for gRPC
  • No way of providing the example values for the requests.
  • Bare-bone styling - you can only select two main colors or customize it with custom CSS
  • The gRPC is not very well documented - the documentation for gRPC is on another level compared to Smart Docs for REST, e.g., provided in the docs api_config.yaml example is incomplete (15.11.2021).
  • No self-hosted option

Buf

/images/grpc-docs-comparision/library-app-screenshot-buf.png

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.

Pros:

  • Installation steps for Golang. You can also create your template for other languages.
  • Documentation is nice and clean
  • RBAC support

Cons:

  • Paid for private documentation
  • You have to install and configure the CLI tool before proceeding
  • You have to build the packages locally or configure your CI/CD
  • Buf is an early startup - the pricing and business model are still unknown
  • There is no way of defining example values for the structure
  • Try it out feature missing
  • There is no way of customization documentation
  • No self-hosted option

protoc-gen-doc

/images/grpc-docs-comparision/library-app-screenshot-doc.png

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.

Pros:

  • Free and opensource
  • Easy to start
  • Fast and easy to embed in any existing webpage - static HTML
  • Easy to style - the markdown format or custom template

Cons:

  • Documentation for the data structures only (protobuf, not gRPC)
  • Lack of SDK or code generation support
  • Lack of example values for the structures
  • Have to manage custom hosting
  • Have to manage the access to the documentation on your own

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.

Google Endpoints is great if you already have an existing REST API and want to host together with gRPC API - it is the most elastic tool from the comparison but lacks “public mode”.

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

Develop gRPC API 10x faster

  • 1 minute to setup
  • Direct integration with GitHub
  • Autogenerate gRPC and gRPC-Web SDK
  • Live-interact with gRPC endpoints