Go每日一库之110：protoc-gen-doc

luckzack

发布于 2023-09-30 08:35:02

2620

发布于 2023-09-30 08:35:02

文章被收录于专栏：人人都是架构师人人都是架构师

前言

毫无疑问，目前后台开发接口协议应用最广泛的除了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.

安装

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

使用

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

演示

以当前目录 helloworld.proto 为例。

// 使用的 protoc --version 为 libprotoc 3.18.1
// 使用的 protoc-gen-go --version 为 protoc-gen-go v1.27.1
// 使用的 protoc-gen-go-grpc --version 为 protoc-gen-go-grpc 1.1.0
// 使用的 protoc-gen-doc --version 为 protoc-gen-doc version 1.5.0
// 在根目录下执行 protoc 命令
protoc \
--go_out=./gen \
--go-grpc_out=./gen \
--doc_out=./doc \
--doc_opt=html,index.html \
./helloworld.proto

同理，也可生成 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

本文参与?腾讯云自媒体分享计划，分享自作者个人站点/博客。

如有侵权请联系 cloudcommunity@tencent.com 删除