发布日期: 2026-08-05
版本号: v2.30.0

新版本grpc-gateway引入了全新的轻量级OpenAPI v3生成器protoc-gen-openapiv3，并支持可见性选择器、禁用默认错误、注解支持等功能。同时新增了独立的OpenAPI v3文档合并工具openapiv3-merge，并将protoc-gen-openapiv2移至protoc工具链中。修复方面优化了OpenAPI v2与v3的确定性生成、注释映射、参数元数据处理、嵌套路径参数处理、引用包装时的元数据保留等多项问题，并改进了配置选项优先级、字段扩展支持和生成代码的请求处理。文档部分补充了HttpBody下载用法、Go工具依赖选项说明，新增OpenTelemetry跟踪示例并修正了相关链接。测试与基础设施方面增强了切片转换器测试覆盖，移除了Java swagger生成器依赖，并进行了多项CI改进与Bazel缓存优化。

更新内容 （中文）

新功能

  • protoc-gen-openapiv3: 全新精简型 OpenAPI v3 生成器 (#6623)，以及后续改进：
    • 可见性选择器 (#6673)
    • disable_default_errors 选项 (#6672)
    • 注解支持 (#6681)
    • 改进的插件错误提示 (#6937)
    • 查询参数的 field_behavior REQUIRED 支持 (#7180) — @maydietwice
  • openapiv3-merge: 用于合并 OpenAPI v3 文档的新型独立工具 (#6771) — @johanbrandhorst
  • protoc-gen-openapiv2 已移入 protoc 工具链 (#6988) — @EliSauder

修复

变更内容 PR 贡献者
OpenAPI v2：渲染定义前对消息排序以确保确定性 #6732 @alliasgher
OpenAPI v2：枚举注释现写入 description 而非 title #6785 @superShen0916
OpenAPI v2：在参数上包含字段 schema 元数据 #6894 @puneetdixit200
OpenAPI v2：嵌套路径参数的空 body 对象现被省略 #7065 @alliasgher
OpenAPI v3：嵌套路径参数的空 body 对象现被省略 #7068 @alliasgher
OpenAPI v2：当 use_allof_for_refs 包装 $ref 时保留 x-nullable #7026 @pkhanaljc
OpenAPI v2：修复冒号前缀路径段的连接问题 #7191 @Ritik100-AIT
OpenAPI 配置选项优先于 proto 选项 #6973 @maskedmaxx
支持用于 OpenAPI/Swagger 生成的服务文档注释 #6200 @majiayu000
修复 oneof 字段的嵌套 body 路径初始化 #6948 @cyphercodes
移除嵌套 proto3 字段的冗余枚举赋值 #7059 @abhishek-dalbanjan
仅在生成代码中 ParseForm 后排空请求 #7192 @paskozdilar
支持与 use_allof_for_refs 一起使用的字段扩展 #3100 @same-id
在 openapiv3 插件参数中忽略 M 导入路径映射 #6936 @johanbrandhorst

文档

  • 阐明 HttpBody 下载用法 (#6904) — @ketpatil77
  • 阐明 Go 工具依赖选项 (#7042) — @hawk-roy
  • 添加可运行的 OpenTelemetry 追踪示例 (#7110) — @hsdfat
  • 修复 README 中的 SLSA 链接 (#7149) — @ZayanKhan-12
  • 解释用于共享 API 配置的 Buf 策略 (#7147) — @dlanov

测试 / CI / 基础设施

  • 为 convert.go 中的切片转换器增加测试覆盖率 (#7041) — @viniciusmtsantos
  • 移除 Java swagger 生成器测试依赖 (#6735) — @johanbrandhorst
  • CI 改进 — go-version-file 使用、发布工作流标签输入、检出引用修复、node_test 超时、用于浏览器测试的 Node 22 LTS（避免 Node 24 zlib 挂起） (#6627, #6632, #6633, #6867, #6868) — @johanbrandhorst
  • 更好的 Bazel 缓存；dependabot PR 自动合并任务 (#6667, #6668) — @johanbrandhorst
  • 对 openapiv3 文件运行 gazelle；添加缺失的 Bazel 文件 (#6734, #6738) — @johanbrandhorst

新贡献者

@alliasgher, @superShen0916, @puneetdixit200, @ketpatil77, @EliSauder, @maskedmaxx, @hawk-roy, @viniciusmtsantos, @cyphercodes, @abhishek-dalbanjan, @hsdfat, @ZayanKhan-12, @dlanov, @maydietwice, @pkhanaljc, @Ritik100-AIT

完整变更日志: https://github.com/grpc-ecosystem/grpc-gateway/compare/v2.29.0...v2.30.0

更新内容 （原始）

New Features

  • protoc-gen-openapiv3: Brand new minimal OpenAPI v3 generator (#6623), plus follow-ups:
    • Visibility selectors (#6673)
    • disable_default_errors option (#6672)
    • Annotation support (#6681)
    • Improved plugin error surfacing (#6937)
    • field_behavior REQUIRED support for query parameters (#7180) — @maydietwice
  • openapiv3-merge: New standalone tool for merging OpenAPI v3 documents (#6771) — @johanbrandhorst
  • protoc-gen-openapiv2 moved to the protoc toolchain (#6988) — @EliSauder

Fixes

Change PR Contributor
OpenAPI v2: messages sorted before rendering definitions for determinism #6732 @alliasgher
OpenAPI v2: enum comments now go to description instead of title #6785 @superShen0916
OpenAPI v2: include field schema metadata on parameters #6894 @puneetdixit200
OpenAPI v2: omit empty body objects for nested path parameters #7065 @alliasgher
OpenAPI v3: omit empty body objects for nested path parameters #7068 @alliasgher
OpenAPI v2: preserve x-nullable when use_allof_for_refs wraps a $ref #7026 @pkhanaljc
OpenAPI v2: fix path joining for colon-prefixed segments #7191 @Ritik100-AIT
Prioritize OpenAPI config options over proto options #6973 @maskedmaxx
Support Service doc comments for OpenAPI/Swagger generation #6200 @majiayu000
Fix nested body path initialization for oneof fields #6948 @cyphercodes
Remove redundant enum assignment for nested proto3 fields #7059 @abhishek-dalbanjan
Drain request only after ParseForm in generated code #7192 @paskozdilar
Support field extensions with use_allof_for_refs #3100 @same-id
Ignore M import-path mappings in openapiv3 plugin params #6936 @johanbrandhorst

Documentation

  • Clarify HttpBody download usage (#6904) — @ketpatil77
  • Clarify Go tool dependency options (#7042) — @hawk-roy
  • Add a runnable OpenTelemetry tracing example (#7110) — @hsdfat
  • Fix SLSA link in README (#7149) — @ZayanKhan-12
  • Explain Buf strategy for shared API config (#7147) — @dlanov

Tests / CI / Infra

  • Add test coverage for slice converters in convert.go (#7041) — @viniciusmtsantos
  • Remove Java swagger generator test dependency (#6735) — @johanbrandhorst
  • CI improvements — go-version-file usage, release workflow tag input, checkout ref fixes, node_test timeouts, Node 22 LTS for browser tests (avoids a Node 24 zlib hang) (#6627, #6632, #6633, #6867, #6868) — @johanbrandhorst
  • Better Bazel caching; auto-merge job for dependabot PRs (#6667, #6668) — @johanbrandhorst
  • Run gazelle on openapiv3 files; add missing Bazel files (#6734, #6738) — @johanbrandhorst

New Contributors

@alliasgher, @superShen0916, @puneetdixit200, @ketpatil77, @EliSauder, @maskedmaxx, @hawk-roy, @viniciusmtsantos, @cyphercodes, @abhishek-dalbanjan, @hsdfat, @ZayanKhan-12, @dlanov, @maydietwice, @pkhanaljc, @Ritik100-AIT

Full Changelog: https://github.com/grpc-ecosystem/grpc-gateway/compare/v2.29.0...v2.30.0

下载链接