在使用 gRPC 時，常用做法是通過 Protobuf 進行接口及接口參數的定義。
随着接口的增多，單純依靠閱讀 .proto 的方式來檢視接口定義既勞神又費眼，也為其他人浏覽接口帶來了不便。
通過 protoc-gen-doc 可以按照 protobuf 中定義的注釋形成相應的文檔，簡單點說就是根據 .proto 中接口及字段的注釋自動生成一份更适合人看的接口說明書。
關于 protoc-gen-doc 的介紹可以通路該項目開源位址 進行了解。
這裡給一段官方介紹的機翻供參考：
protoc-gen-doc 是 Google Protocol Buffers 編譯器 (protoc) 的文檔生成器插件。
該插件可以從 .proto 檔案中的注釋生成 HTML、JSON、DocBook 和 Markdown 文檔。
它支援 proto2 和 proto3，并且可以在相同的上下文中處理兩者。
工具配置
進行文檔的生成前需要進行如下準備工作：
1.下載下傳 protoc；
2.下載下傳 protoc-gen-doc；
protoc 的下載下傳請通路項目開源位址下載下傳最新版本對應的 windows release package（本文編開源項目 Release 發
proto-gen-doc 的下載下傳亦請通路項目開源位址下載下傳最新版本對應的 windows release package 下載下傳至本地的壓縮包直接解壓，将解壓出的 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=[輸入檔案關聯位址]
* 此處需要注意 輸出檔案目錄 需要在執行指令前預先建立好，否則會由于找不到輸出目錄而報錯
示例（生成 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 的文檔，大家可以根據需要自行探索~