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;
}