protoc-gen-doc
这是一个用于 Google Protocol Buffers 编译器(protoc
)的文档生成器插件。该插件可以从 .proto
文件中的注释生成 HTML、JSON、DocBook 和 Markdown 文档。
它支持 proto2 和 proto3,并且可以在同一上下文中处理两者(请查看 示例 以获取证明)。
安装
有一个可用的 Docker 镜像(docker pull pseudomuto/protoc-gen-doc
),其中包含了从 proto 文件生成文档所需的一切。
如果你想在本地安装,可以使用 go get
命令。
go install github.com/pseudomuto/protoc-gen-doc/cmd/protoc-gen-doc@latest
或者,你可以从 releases 页面下载适用于你的平台的预构建版本。
最后,该插件也可在 Maven Central 上获得。有关如何使用它的详细信息,请查看 gradle 示例。
调用插件
通过向 protoc
编译器传递 --doc_out
和 --doc_opt
选项来调用插件。该选项的格式如下:
--doc_opt=<格式>|<模板文件名>,<输出文件名>[,default|source_relative]
格式可以是内置格式之一(docbook
、html
、markdown
或 json
)或包含自定义 Go 模板 的文件名。
如果指定了 source_relative
标志,输出文件将写入与输入文件相同的相对目录。
使用 Docker 镜像(推荐)
Docker 镜像有两个卷:/out
和 /protos
,分别是用于写入文档的目录和包含 proto 文件的目录。
你可以通过运行以下命令为示例生成 HTML 文档:
docker run --rm \
-v $(pwd)/examples/doc:/out \
-v $(pwd)/examples/proto:/protos \
pseudomuto/protoc-gen-doc
默认情况下,会为 /protos
卷中的所有 .proto
文件在 /out/index.html
中生成 HTML 文档。可以通过向容器传递 --doc_opt
参数来更改此设置。
例如,为所有示例生成 Markdown:
docker run --rm \
-v $(pwd)/examples/doc:/out \
-v $(pwd)/examples/proto:/protos \
pseudomuto/protoc-gen-doc --doc_opt=markdown,docs.md
你还可以为单个文件生成文档。这可以通过向命令传递文件来完成:
docker run --rm \
-v $(pwd)/examples/doc:/out \
-v $(pwd)/examples/proto:/protos \
pseudomuto/protoc-gen-doc --doc_opt=markdown,docs.md Booking.proto [可选列出更多文件]
你还可以排除与特定路径表达式匹配的 proto 文件。这可以通过传递第二个由 :
分隔的选项来完成。例如,你可以将任意数量的逗号分隔模式作为第二个选项传递:
docker run --rm \
-v $(pwd)/examples/doc:/out \
-v $(pwd)/examples/proto:/protos \
pseudomuto/protoc-gen-doc --doc_opt=:google/*,somepath/*
注意:路径应该是容器内的路径,而不是主机上的路径!
注意:由于 Docker 中通配符扩展的工作方式,你不能在文件列表中使用通配符路径(例如
protos/*.proto
)。为了解决这个问题,如果没有传递文件,容器将为protos/*.proto
生成文档,可以通过挂载不同的卷来更改。
简单用法
例如,要为 proto
目录中的所有 .proto
文件生成 HTML 文档并输出到 doc/index.html
,请输入:
protoc --doc_out=./doc --doc_opt=html,index.html proto/*.proto
插件可执行文件必须在 PATH
中才能使用。
使用预编译的二进制文件
或者,你可以使用 --plugin
选项指定预构建的/不在 PATH
中的二进制文件。
protoc \
--plugin=protoc-gen-doc=./protoc-gen-doc \
--doc_out=./doc \
--doc_opt=html,index.html \
proto/*.proto
使用自定义模板
如果你想使用自己的模板,只需使用模板文件的路径而不是类型。
protoc --doc_out=./doc --doc_opt=/path/to/template.tmpl,index.txt proto/*.proto
有关可用模板参数和函数的信息,请参阅 自定义模板。如果你只想自定义 HTML 输出的外观,请将你的 CSS 放在输出文件旁边的 stylesheet.css
中,它将被自动识别。
编写文档
可以为消息、字段、服务(及其方法)、枚举(及其值)、扩展和文件编写文档。一般来说,注释有两种形式:前导注释和尾随注释。
前导注释
前导注释可以在任何地方使用。
/**
* 这是一个消息的前导注释
*/
message SomeMessage {
// 这是另一个前导注释
string value = 1;
}
注意:文件级注释应该是语法指令的前导注释。
尾随注释
字段、服务方法、枚举值和扩展支持尾随注释。
enum MyEnum {
DEFAULT = 0; // 默认值
OTHER = 1; // 其他值
}
排除注释
如果你想在 proto 文件中保留一些注释,但不希望它们成为文档的一部分,你可以简单地在注释前加上 @exclude
前缀。
示例:仅包含 id
字段的注释
/**
* @exclude
* 这个注释不会被渲染
*/
message ExcludedMessage {
string id = 1; // 此消息的 id。
string name = 2; // @exclude 此消息的名称
/* @exclude 此消息的值。 */
int32 value = 3;
}
查看 示例 proto 文件 以了解所有选项。
输出示例
使用输入 .proto
文件
插件生成以下输出
查看 Makefile 中的 examples
任务以了解如何生成这些文件。