pseudomuto/protoc-gen-doc

# protoc-gen-doc [][ci-url] [][codecov-url] [][godoc-url] [][goreport-url] 这是一个用于 Google Protocol Buffors 编译器 (`protoc`) 的文档生成插件。该插件可以从您的 `.proto` 文件中的注释生成 HTML、JSON、DocBook 和 Markdown 文档。 它支持 proto2 和 proto3，并且可以在同一上下文中同时处理两者（请参阅[示例](examples/)以获取证明）。 ## 安装 我们提供了一个 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 示例](examples/gradle)。 ## 调用插件 通过向 `protoc` 编译器传递 `--doc_out` 和 `--doc_opt` 选项来调用该插件。该选项具有 以下格式： ``` --doc_opt=|,[,default|source_relative] ``` 格式可以是内置格式之一（`docbook`、`html`、`markdown` 或 `json`） 或者是包含自定义 [Go template][gotemplate] 的文件名。 如果指定了 `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 [OPTIONALLY LIST MORE FILES] ``` 您还可以排除匹配特定路径表达式的 proto 文件。这是通过传递由 `:` 分隔的第二个选项来完成的。例如，您可以将任意数量的逗号分隔模式作为第二个选项传递： ``` docker run --rm \ -v $(pwd)/examples/doc:/out \ -v $(pwd)/examples/proto:/protos \ pseudomuto/protoc-gen-doc --doc_opt=:google/*,somepath/* ``` _**切记**_：路径应该是容器内的路径，而不是宿主机的路径！ ### 简单用法 例如，要将 `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 ``` 有关可用的模板参数和函数的信息，请参阅[自定义模板][custom]。如果您只是 想自定义 HTML 输出的外观，请将您的 CSS 放在输出文件旁边的 `stylesheet.css` 中，它会被自动加载。 ## 编写文档 消息、字段、服务（及其方法）、枚举（及其值）、扩展和文件都可以被记录在文档中。 一般来说，注释有两种形式：前导注释和尾随注释。 **前导注释** 前导注释可以在任何地方使用。 ``` /** * This is a leading comment for a message */ message SomeMessage { // this is another leading comment string value = 1; } ``` **尾随注释** ``` enum MyEnum { DEFAULT = 0; // the default value OTHER = 1; // the other value } ``` **排除注释** 如果您想在 proto 文件中保留某些注释，但不希望它们成为文档的一部分，您只需 在注释前加上 `@exclude` 前缀。 示例：仅包含 `id` 字段的注释 ``` /** * @exclude * This comment won't be rendered */ message ExcludedMessage { string id = 1; // the id of this message. string name = 2; // @exclude the name of this message /* @exclude the value of this message. */ int32 value = 3; } ``` 查看[示例 proto](examples/proto) 以了解所有选项。 ## 输出示例 使用输入的 `.proto` 文件 * [Booking.proto](examples/proto/Booking.proto) * [Customer.proto](examples/proto/Customer.proto) * [Vehicle.proto](examples/proto/Vehicle.proto) 插件给出的输出 * [Markdown](examples/doc/example.md) * [HTML][html_preview] * [DocBook](examples/doc/example.docbook) * [JSON](examples/doc/example.json) 查看 [Makefile](Makefile) 中的 `examples` 任务，了解它们是如何生成的。

标签：EVTX分析, 安全监控, 日志审计, 请求拦截