google/gnostic

[](https://github.com/google/gnostic/actions) # ⨁ gnostic 本仓库包含一个 Go 命令行工具，它可以将 JSON 和 YAML [OpenAPI](https://github.com/OAI/OpenAPI-Specification) 描述转换为 等效的 Protocol Buffer 表示，或进行反向转换。 [Protocol Buffers](https://developers.google.com/protocol-buffers/) 提供了 一种语言中立、平台中立且可扩展的机制，用于序列化 结构化数据。**gnostic** 的 OpenAPI Protocol Buffer 模型可用于生成代码，这些代码包含的数据结构带有 OpenAPI 描述元素的显式字段。这使得开发人员能够以类型安全的方式处理 OpenAPI 描述，这在像 Go 和 [Dart](https://dart.dev/) 这样的强类型语言中尤其有用。 **gnostic** 的编译代码和 OpenAPI Protocol Buffer 模型 是根据 [OpenAPI JSON Schema](https://github.com/OAI/OpenAPI-Specification/blob/master/schemas/v2.0/schema.json) 自动生成的。 生成器的源代码位于 [generate-gnostic](generate-gnostic) 目录中。 ## 相关仓库 [google/gnostic-models](https://github.com/google/gnostic-models) 包含 本项目生成的 protobuf 模型的轻量级发行版。 当只需要这些模型的低依赖集成时，Go 项目可以改为从 `gnostic-models` 而不是 `gnostic` 导入包。 [google/gnostic-grpc](https://github.com/google/gnostic-grpc) 包含一个 gnostic 插件，它可以生成 API 的带注解的 Protocol Buffer 描述，当进行代码转码时，会生成符合指定 OpenAPI 文档的 API。要从 protobuf 转到 OpenAPI，请参阅 本项目中的 [protoc-gen-openapi](cmd/protoc-gen-openapi) 工具。 [google/gnostic-go-generator](https://github.com/google/gnostic-go-generator) 包含一个实验性的 gnostic 插件，它可为指定的 OpenAPI 文档描述的 API 生成 Go 客户端。 ## 免责声明 欢迎提供反馈和贡献！在发布 1.0 版本之前，请 将此视为预发布软件和正在进行的工作。为了确保稳定的 构建，我们请求依赖项目始终引用带有标签的 **gnostic** 发行版。 ## 要求 **gnostic** 可以在支持 [Go](http://golang.org) 和 [Protocol Buffer Compiler](https://github.com/protocolbuffers/protobuf) 的任何环境中运行。 ## 安装和入门 以下说明适用于使用 [Go modules](https://blog.golang.org/using-go-modules) 安装 **gnostic**，该功能受 Go 1.11 及更高版本支持。 1. 通过使用 `git clone` 下载来获取此包。 git clone https://github.com/google/gnostic cd gnostic 2. 验证您是否拥有本地安装的 `protoc`。您可以从 [这里](https://github.com/protocolbuffers/protobuf) 获取 `protoc`。 3. 使用 `make` 构建 **gnostic**。这会使用 [go generate](https://blog.golang.org/generate) 构建支持代码， 包括由 `protoc` 和 Go `protoc` 插件生成的代码，该插件会 由 [COMPILE-PROTOS.sh](COMPILE-PROTOS.sh) 脚本自动从 [github.com/golang/protobuf](https://github.com/golang/protobuf) 下载。这也会构建本仓库中的所有插件 和相关工具。 4. 使用 `make test` 验证 **gnostic**。这些测试由 **gnostic** 的 持续集成运行，因此您应该期望它们在所有发行版本中都能通过。 5. 运行 **gnostic**。此示例调用会在当前 目录中创建一个名为 `petstore.pb` 的文件，其中包含示例 API 的二进制 Protocol Buffer 描述。 gnostic --pb-out=. examples/v2.0/json/petstore.json 6. 您还可以编译使用 URL 指定的文件。这是编译 先前示例的另一种方法。这次我们将创建 `petstore.text`， 其中包含 Protocol Buffer 描述的文本表示。 这主要用于测试和调试。 gnostic --text-out=petstore.text https://raw.githubusercontent.com/google/gnostic/master/examples/v2.0/json/petstore.json 7. 有关示例应用程序，请参阅 apps/report。它读取由 **gnostic** 创建的二进制 Protocol Buffer 编码。 go install ./apps/report ## 由顶层 Makefile 自动安装 report petstore.pb 8. **gnostic** 还支持插件。**gnostic** 的插件接口 是仿照 `protoc` 的 [plugin.proto](https://github.com/protocolbuffers/protobuf/blob/master/src/google/protobuf/compiler/plugin.proto) 建模的，并在 [plugins/plugin.proto](plugins/plugin.proto) 中进行了描述。在 `plugins` 目录中实现了几个 插件。其他的，例如 [gnostic-grpc](https://github.com/google/gnostic-grpc) 和 [gnostic-go-generator](https://github.com/google/gnostic-go-generator)， 则发布在它们各自的仓库中。其中一个这样的插件是 [gnostic-vocabulary](plugins/gnostic-vocabulary)，它会生成 API 接口中 单词使用情况的摘要。您可以使用以下命令运行 `gnostic-vocabulary`： gnostic examples/v2.0/json/petstore.json --vocabulary_out=. 这将在 `examples/v2.0/json` 中生成名为 `vocabulary.pb` 和 `vocabulary.json` 的文件。有关 `vocabulary.pb` 的格式，请参阅 [metrics/vocabulary.proto](metrics/vocabulary.proto)。 9. [可选] **gnostic** 的很大一部分是由 [generate-gnostic](generate-gnostic) 工具自动生成的。它使用 JSON schema 生成 Protocol Buffer 语言文件，用于描述受支持的 API 规范格式，以及 Go 语言代码文件，用于将 JSON 或 YAML API 描述读取到生成的 protocol buffer 模型中。 这些文件的预生成版本已被提交到 [openapiv2](openapiv2)、[openapiv3](openapiv3) 和 [discovery](discovery) 目录中。您可以使用以下命令重新生成此代码： go install ./generate-gnostic generate-gnostic --v2 generate-gnostic --v3 generate-gnostic --discovery ## 版权所有 Copyright 2017-2020, Google LLC. ## 许可证 在 Apache 2.0 许可证下发布。

标签：API编译器, EVTX分析, Go, OpenAPI, Protocol Buffers, Ruby工具, SOC Prime, 代码生成, 开发工具, 日志审计, 渗透测试工具, 调试插件