gRPC Swagger vs protoc-gen-doc

gRPC Swagger is a free, open-source debugging tool for discovering and calling gRPC methods through Swagger UI. It uses server reflection to scan a registered endpoint, identified by host and port, and then displays available services, method definitions, and parameters. Users can invoke methods with Swagger UI’s “Try it out” control, supplying request data and headers as JSON; the headers are passed to the gRPC server as metadata. Reflection must be enabled on the gRPC service, but the setup instructions say proto files and related implementations do not need modification. The project runs from a released JAR or from source and defaults to port 8080. Configuration can show registered services and expire inactive registrations after a chosen number of seconds. Documented endpoints cover registration, service listing, method calls, and Swagger documentation. It is self-hosted, available for API and web use, and licensed under MIT.

protoc-gen-doc is a documentation generator plugin for the Google Protocol Buffers compiler. It turns comments in .proto files into HTML, JSON, DocBook, or Markdown documentation, covering files, messages, fields, services and methods, enums and values, and extensions. It supports proto2 and proto3, including both in the same context. You can exclude files with path patterns and omit comments marked with the @exclude prefix. The plugin runs through protoc with the --doc_out and --doc_opt options; its source_relative flag places generated output in the same relative directory as the input. For customization, users can supply a Go template or use a stylesheet.css file to change HTML appearance. Installation options include Go, prebuilt releases, a Docker image, and a Maven Central package. It runs on Linux, macOS, and Windows and is self-hosted. The project is free under the MIT License, which allows use, modification, distribution, sublicensing, and sale under its terms. The license provides the software as is, without warranty.