前言

毫无疑问，目前后台开发接口协议应用最广泛的除了HTTP之外就是gRPC了，HTTP接口有成熟的swagger工具可以生成界面美观和使用友好的文档，那么对于gRPC呢？

所以通过 .proto 文件能否生成更易阅读的 HTML 接口文档？

protoc-gen-doc

protoc-gen-doc This is a documentation generator plugin for the Google Protocol Buffers compiler (protoc). The plugin can generate HTML, JSON, DocBook and Markdown documentation from comments in your .proto files.

安装

  1. go install github.com/pseudomuto/protoc-gen-doc/cmd/protoc-gen-doc@latest

使用

  1. --doc_out=helloworld/doc \
  2. --doc_opt=html,index.html

演示

以当前目录 helloworld.proto 为例。

  1. // 使用的 protoc --version 为 libprotoc 3.18.1
  2. // 使用的 protoc-gen-go --version 为 protoc-gen-go v1.27.1
  3. // 使用的 protoc-gen-go-grpc --version 为 protoc-gen-go-grpc 1.1.0
  4. // 使用的 protoc-gen-doc --version 为 protoc-gen-doc version 1.5.0
  5. // 在根目录下执行 protoc 命令
  6. protoc \
  7. --go_out=./gen \
  8. --go-grpc_out=./gen \
  9. --doc_out=./doc \
  10. --doc_opt=html,index.html \
  11. ./helloworld.proto

每日一库之110：protoc-gen-doc - 图1
同理，也可生成 JSON、Markdown 文档，去试试吧。

关于proto文件中的注释规则可参考：
https://github.com/pseudomuto/protoc-gen-doc/#writing-documentation
https://github.com/pseudomuto/protoc-gen-doc/blob/master/examples/proto/Booking.proto