Windows 下使用 protoc-gen-doc 生成 protobuf 接口文档
在使用 gRPC 时，常用做法是通过 Protobuf 进行接口及接口参数的定义。
随着接口的增多，单纯依靠阅读 .proto 的方式来查看接口定义既劳神又费眼，也为其他人浏览接口带来了不便。
通过 protoc-gen-doc 可以按照 protobuf 中定义的注释形成相应的文档，简单点说就是根据 .proto 中接口及字段的注释自动生成一份更适合人看的接口说明书。
关于 protoc-gen-doc 的介绍可以访问该项目开源地址 https://github.com/pseudomuto/protoc-gen-doc#invoking-the-plugin 进行了解。
这里给一段官方介绍的机翻供参考：
protoc-gen-doc 是 Google Protocol Buffers 编译器 (protoc) 的文档生成器插件。
该插件可以从 .proto 文件中的注释生成 HTML、JSON、DocBook 和 Markdown 文档。
它支持 proto2 和 proto3，并且可以在相同的上下文中处理两者。
工具配置
进行文档的生成前需要进行如下准备工作：
1.下载 protoc；
2.下载 protoc-gen-doc；
protoc 的下载请访问项目开源地址下载最新版本对应的 windows release package（本文编写时对应的是 protoc-3.17.3-win64.zip）
开源项目 Release 发布地址为 Releases · protocolbuffers/protobuf (github.com)
proto-gen-doc 的下载亦请访问项目开源地址下载最新版本对应的 windows release package （本文编写时对应的是 protoc-gen-doc.1.5.0.windows-amd64.go1.16.6.tar.gz）
开源项目 Release 发布地址为 Releases · pseudomuto/protoc-gen-doc (github.com)
下载至本地的压缩包直接解压，将解压出的 protoc.exe 及 protoc-gen-doc.exe 移至任意目录内（本文中将其移动至 D:\Protoc 目录下）
然后我们在系统环境变量的 Path 中添加该目录的地址（我的电脑 -> 属性 -> 高级系统设置 -> 环境变量 -> 系统变量 -> Path）
添加完成后我们可以在控制台中输入 protoc --version 来检验是否配置成功（当然也可以不配置环境变量，直接在 protoc.exe 所在目录执行命令）
同样执行 protoc-gen-doc --version 也能应能检查出 gen-doc 对应的版本
生成文档
工具准备完成后我们现在可以开始进行文档的生成了
生成文档的命令中需要指定四个关键信息
一是 输出文件的目录路径
二是 输出文档的类型及输出文件名称
三是 输入文件的详细路径
四是 输入文件关联地址（示例中详细说明该参数使用方法，我在这里困扰了很久）
命令的格式为 protc --doc_out=[输出文件目录路径] --doc_opt=[文档类型],[输出文件名称] [输入文件路径] --proto_path=[输入文件关联地址]
* 此处需要注意 输出文件目录 需要在执行命令前预先创建好，否则会由于找不到输出目录而报错
详细的命令使用方式可参考
pseudomuto/protoc-gen-doc: Documentation generator plugin for Google Protocol Buffers (github.com)
示例（生成 html 文档）：
我们在 F 盘下创建 protobuf_doc 目录，在其下创建 docs 及 proto 两个目录，
将需要生成文档的 .proto 文件放置在 F:\protobuf_doc\proto\ 目录内
随后启动控制台，在其中键入命令并回车执行
protoc --doc_out=f:\protobuf_doc\docs --doc_opt=html,index.html f:\protobuf_doc\proto\*.ptoto --proto_path=f:\protobuf_doc
* 上述命令表示我们需要将 f:\protobuf_doc\proto 目录下的所有后缀为 .proto 的文件按照 html 文档的方式生成至名为 index.html 的文件中，并最终输出到 f:\protobuf_dod\docs 目录下
* 关于 --proto_path 参数
1. 最初从官方说明和网上查找到的资料中没有看到关于这个参数的介绍（可能是我英文太烂）
所以一开始执行命令总会得到如下的提示
File does not reside within any path specified using --proto_path (or -I). You must specify a --proto_path which encompasses this file. Note that the proto_path must be an exact prefix of the .proto file names -- protoc is too dumb to figure out when two paths (e.g. absolute and relative) are equivalent (it's harder than you think).
提示我们文件不在任何一个路径中（找不到）
因此我们需要使用 --proto_path 参数来告诉 protoc 应该在哪些目录下查找关联的 proto 文件
2. 另外一种情况就是在输入文件中如果包含了 impot 即从其他 proto 中引入的动作，也会提示我们找不到引入的文件
例如我们在 x1.proto 中定义了 import "proto/x2.proto"; 那么在生成 x1.proto 的文档时会提示找不到 x2.proto
此时我们也应使用 --proto_path 参数来告知 protoc 关联文件的查找目录
特别需要注意的是 --proto_path 跟随的目录不要与 import 中声明的目录重叠
即 .proto 文件的存放路径为 f:\protobuf-doc\proto\，x1 => impot "proto/x2.proto" 则 --proto_path=f:\protobuf_doc 即可，
(个人理解) 也就是说 protoc 会在 --proto_path 指定的目录下去寻找 import 的内容，
如果我们指定的 --proto_path 和 import 的目录存在重叠比如写成了 f:\protobuf_doc\proto，则查找时会变为在 f:\protobuf_doc\proto\proto\ 下查找 x2.proto，所以仍然找不到
执行完成后我们便可以在 docs 目录下查看到生成完毕的文档了
双击打开看一看，更像是人可以阅读的东西啦~
以上就是在 Windows 下利用 protoc-gen-doc 生成 Protobuf 文档的简单步骤，
该工具除了 Html 之外还可以生成 JSON, DocBook, Markdown 的文档，大家可以根据需要自行探索~
文章中的内容和思路可能存在错误和缺陷，如有偏颇还请谅解，也欢迎与我沟通进行指正。
