在使用 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 目錄下
執行完成后我們便可以在 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，所以仍然找不到
以上就是在 Windows 下利用 protoc-gen-doc 生成 Protobuf 文檔的簡單步驟，
該工具除了 Html 之外還可以生成 JSON, DocBook, Markdown 的文檔，大家可以根據需要自行探索~
文章中的內容和思路可能存在錯誤和缺陷，如有偏頗還請諒解，也歡迎與我溝通進行指正。