openapi2proto: OpenAPI 到 Protobuf 的转换工具

1. 项目介绍

openapi2proto 是一个由知名媒体机构开发的开源工具，它允许您从 OpenAPI 规范（也称为 Swagger）文件自动生成 Protobuf v3 架构和 gRPC 服务定义。这个工具简化了将 RESTful API 转换为高效、类型安全的 gRPC 服务的过程。

2. 项目快速启动

安装

确保已安装了 Go，并且 $GOPATH/bin 在您的系统路径中。然后，您可以运行以下命令来获取并安装 openapi2proto：

go install github.com/NYTimes/openapi2proto/cmd/openapi2proto@latest

对于 Go 1.15 之前的版本，使用下面的命令：

go get -u github.com/NYTimes/openapi2proto/cmd/openapi2proto

使用

要运行该工具，您需要提供一个 OpenAPI 规范文件。这里是一个基本示例：

openapi2proto -spec path/to/openapi.yaml -out generated.proto

这将会把规范转换成名为 generated.proto 的文件，默认采用四个空格作为缩进。如果您想包含额外的 google.api.http 注解以供 grpc-gateway 用户使用，可以加上 -annotate 标志：

openapi2proto -spec path/to/openapi.yaml -annotate -out generated.proto

3. 应用案例和最佳实践

• 微服务集成：在多服务架构中，使用 openapi2proto 可以统一不同的服务接口定义，促进跨团队协作。
• API 文档自动化：转换后的 Protobuf 文件可结合 gRPC 工具链，自动生成清晰的 API 文档。
• 测试：利用 gRPC 测试框架对转换后的服务进行端到端测试，提高测试覆盖率。

最佳实践包括：

• 确保 OpenAPI 规范文件的完整性和准确性。
• 对复杂的接口进行拆分，避免单个 .proto 文件过于庞大。
• 使用 -skip-rpcs 或 -skip-deprecated-rpcs 参数，根据需求选择是否生成某些 RPC。

4. 典型生态项目

• gRPC: gRPC 是 Google 开源的一种高性能、通用的 RPC 框架，基于 Protobuf。
• gRPC Gateway: 将 gRPC 服务映射到 REST API 的代理，让非 gRPC 客户端能够继续调用服务。
• OpenAPI Generator: 除了 openapi2proto，还有其他工具可以从 OpenAPI 转换为多种语言的服务实现。

通过这些工具，开发者可以在 REST 和 gRPC 之间轻松切换，同时也保留了强类型和自动化的优点。