尧图网站建设 
grpc-gateway 怎么生成 OpenAPI 3.1 并隐藏 INTERNAL/PREVIEW 标注的元素【免费下载链接】grpc-gatewaygRPC to JSON proxy generator following the gRPC HTTP spec项目地址: https://gitcode.com/GitHub_Trending/gr/grpc-gateway如果你用 gRPC 对外提供 HTTP/JSON 接口需要一份 OpenAPI 3.1 文档但又不希望把内部INTERNAL或未发布PREVIEW的字段、方法、服务、枚举值暴露出去grpc-gateway 的protoc-gen-openapiv3生成器可以直接完成这两件事从带google.api.http标注的 proto 文件生成 OpenAPI 3.1.0 JSON同时依据google.api.VisibilityRule注解和visibility_restriction_selectors选项把不满足条件标注的元素从输出中丢弃。本文的操作路径基于仓库中的 docs/docs/mapping/openapi_v3.md 和示例 proto examples/internal/proto/examplepb/visibility_rule_echo_service.proto。先说清一个前提protoc-gen-openapiv3目前是 Alpha 状态文档明确提示其输出形状可能在次版本之间变化oneof、wrapper 类型、枚举和 path-template 展开的编码方式都还会演进。文档的建议是需要生产稳定的 OpenAPI 管线时改用protoc-gen-openapiv2见 docs/docs/mapping/customizing_openapi_output.md。如果你能接受这个不稳定窗口继续按下面的步骤操作。准备条件安装生成器插件go install github.com/grpc-ecosystem/grpc-gateway/v2/protoc-gen-openapiv3latest你的 proto 文件需要同时导入两个 Google API 定义文件annotations.proto用于 HTTP 绑定visibility.proto用于可见性标注import google/api/annotations.proto; import google/api/visibility.proto;proto 中至少有一个带 HTTP 绑定的 service。生成器会为每个声明了 HTTP 绑定的 proto 文件输出一份 OpenAPI JSONfoo.proto→foo.openapi.json没有 HTTP 绑定 service 的文件不产生输出。给元素打 INTERNAL / PREVIEW 标注可见性标注使用google.api.VisibilityRule可以加在 service、method、field 和枚举值上。仓库示例 proto 展示了完整的用法摘自 examples/internal/proto/examplepb/visibility_rule_echo_service.protosyntax proto3; package grpc.gateway.examples.internal.proto.examplepb; import google/api/annotations.proto; import google/api/visibility.proto; // SimpleMessage represents a simple message sent to the Echo service. message VisibilityRuleSimpleMessage { enum VisibilityEnum { VISIBILITY_ENUM_UNSPECIFIED 0; VISIBILITY_ENUM_VISIBLE 1; VISIBILITY_ENUM_INTERNAL 2 [(google.api.value_visibility).restriction INTERNAL]; VISIBILITY_ENUM_PREVIEW 3 [(google.api.value_visibility).restriction INTERNAL,PREVIEW]; } // Id represents the message identifier. string id 1; string internal_field 8 [(google.api.field_visibility).restriction INTERNAL]; string preview_field 9 [(google.api.field_visibility).restriction INTERNAL,PREVIEW]; VisibilityEnum an_enum 10; } service VisibilityRuleEchoService { // Echo method receives a simple message and returns it. // It should always be visible in the open API output. rpc Echo(VisibilityRuleSimpleMessage) returns (VisibilityRuleSimpleMessage) { option (google.api.http) {post: /v1/example/echo/{id}}; } // EchoInternal is an internal API that should only be visible in the OpenAPI spec // if visibility_restriction_selectors includes INTERNAL. rpc EchoInternal(VisibilityRuleSimpleMessage) returns (VisibilityRuleSimpleMessage) { option (google.api.method_visibility).restriction INTERNAL; option (google.api.http) {get: /v1/example/echo_internal}; } } // VisibilityRuleInternalEchoService service responds to incoming echo requests. // It should only be visible in the OpenAPI spec if visibility_restriction_selectors includes INTERNAL. service VisibilityRuleInternalEchoService { option (google.api.api_visibility).restriction INTERNAL; // Echo method receives a simple message and returns it. // It should not be visible in the open API output. rpc Echo(VisibilityRuleSimpleMessage) returns (VisibilityRuleSimpleMessage) { option (google.api.http) {post: /v1/example/internal/echo/{id}}; } }四个标注入口分别对应不同粒度字段[(google.api.field_visibility).restriction INTERNAL]方法option (google.api.method_visibility).restriction INTERNAL;整个服务option (google.api.api_visibility).restriction INTERNAL;枚举值[(google.api.value_visibility).restriction INTERNAL]。restriction 的标签取值是任意的INTERNAL和PREVIEW只是约定俗成的组合ALPHA、BETA、RELEASED等都可以只要 proto 注解和生成器选项用同一套词汇即可。restriction 也可以写多个标签逗号分隔如示例中的INTERNAL,PREVIEW表示该元素在两个标签任一被选中时都会出现。生成 OpenAPI 3.1 并隐藏 INTERNAL / PREVIEW 元素隐藏逻辑的核心规则是带VisibilityRule标注的元素只有当其 restriction 标签与配置的visibility_restriction_selectors有交集时才会保留没有标注的元素始终输出。所以要让INTERNAL/PREVIEW标注的元素不进入文档最直接的做法就是生成时不传这两个 selector。buf 方式主路径。buf.gen.yaml中只配置插件本身不加visibility_restriction_selectorsversion: v2 plugins: - local: protoc-gen-openapiv3 out: .然后运行buf generate。每个声明了 HTTP 绑定的 proto 文件旁边会出现对应的.openapi.json文件。protoc 方式。等价的命令protoc -I. \ --openapiv3_out. \ path/to/your/service.proto可选分支部分保留。如果你希望对外文档保留PREVIEW元素但只隐藏INTERNAL元素只配置一个 selector 即可例如 bufversion: v2 plugins: - local: protoc-gen-openapiv3 out: . opt: - visibility_restriction_selectorsPREVIEW或 protocprotoc -I. \ --openapiv3_out. \ --openapiv3_optvisibility_restriction_selectorsPREVIEW \ path/to/your/service.proto这个配置下标注为INTERNAL,PREVIEW的元素如示例中的EchoInternalAndPreview方法、preview_field字段会保留而只标注INTERNAL的元素被丢弃。反过来若同时声明两个 selector文档给出的多 selector 写法是多个opt条目opt: - visibility_restriction_selectorsPREVIEW - visibility_restriction_selectorsINTERNALINTERNAL和PREVIEW标注的元素就都会进入输出。selector 的增减直接决定哪些标注元素可见用同一套词汇即可。验证隐藏效果对生成的.openapi.json逐项核对以下行为它们均由文档明确定义普通元素无标注的 service、方法、字段、枚举值照常出现示例中的Echo方法、id字段。被隐藏的方法/v1/example/echo_internal对应的 operation 不应出现在paths中。被隐藏的服务整服务隐藏时其所有方法一并消失且该服务的 tag 从tags[]中省略。被隐藏的字段internalField、previewFieldJSON 命名不应出现在请求/响应 schema 的 properties 中。oneof 组当某个oneof组的字段全部被隐藏时该组 at most one set 约束一并被移除而不是留下空约束。枚举某个枚举值被隐藏后schema 的enum列表中不再出现该值如果枚举的所有值都被隐藏组件 schema 仍会输出可见字段可能引用它但退化为无约束的type: string此时生成器会写一行日志提示——看到这个日志就说明存在全隐藏的枚举需要放宽 selector 或隐藏引用它的字段。两条容易踩坑的规则要提前知道用作 HTTP 路径参数的字段上的可见性标注会被忽略——path template 本身始终暴露参数名。要隐藏一个接收受限输入的 operation应把google.api.method_visibility加在方法上或整服务用google.api.api_visibility而不是标注 path 字段。输出是确定的paths 按 RPC 声明顺序输出组件 schema 按字母排序响应码先默认后排序。因此可以用两次生成结果对比的方式验证 selector 变更确实影响了输出。文档还给出了一个端到端参考examples/internal/integration/openapiv3 展示了一个真实 grpc-gateway 跑在生成客户端后面的集成示例最小输出的对照样例见 protoc-gen-openapiv3/internal/genopenapi/testdata/simple_echo.openapi.json。边界与限制protoc-gen-openapiv3不消费grpc.gateway.protoc_gen_openapiv2.options注解集依赖 v2 那套注解标题、文档元信息等时要继续用protoc-gen-openapiv2。生成器不支持 YAML 输出只产出 JSON枚举一律按字符串渲染组件名固定为去掉前导点的完整 proto 全限定名如lib.v1.Book。由于是 Alpha 输出oneof、wrapper 类型、枚举、path-template 展开的编码规则可能随版本变化锁定版本后再进生产流程。可见性逻辑的实现入口是 protoc-gen-openapiv3/internal/genopenapi/visibility.goisVisible函数即restriction 标签与 selector 求交集这一判断的实现行为与上文一致。【免费下载链接】grpc-gatewaygRPC to JSON proxy generator following the gRPC HTTP spec项目地址: https://gitcode.com/GitHub_Trending/gr/grpc-gateway创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 grpc-gateway 怎么生成 OpenAPI 3.1 并隐藏 INTERNAL/PREVIEW 标注的元素？
grpc-gateway 怎么生成 OpenAPI 3.1 并隐藏 INTERNAL/PREVIEW 标注的元素【免费下载链接】grpc-gatewaygRPC to JSON proxy generator following the gRPC HTTP spec项目地址: https://gitcode.com/GitHub_Trending/gr/grpc-gateway如果你用 gRPC 对外提供 HTTP/JSON 接口需要一份 OpenAPI 3.1 文档但又不希望把内部INTERNAL或未发布PREVIEW的字段、方法、服务、枚举值暴露出去grpc-gateway 的protoc-gen-openapiv3生成器可以直接完成这两件事从带google.api.http标注的 proto 文件生成 OpenAPI 3.1.0 JSON同时依据google.api.VisibilityRule注解和visibility_restriction_selectors选项把不满足条件标注的元素从输出中丢弃。本文的操作路径基于仓库中的 docs/docs/mapping/openapi_v3.md 和示例 proto examples/internal/proto/examplepb/visibility_rule_echo_service.proto。先说清一个前提protoc-gen-openapiv3目前是 Alpha 状态文档明确提示其输出形状可能在次版本之间变化oneof、wrapper 类型、枚举和 path-template 展开的编码方式都还会演进。文档的建议是需要生产稳定的 OpenAPI 管线时改用protoc-gen-openapiv2见 docs/docs/mapping/customizing_openapi_output.md。如果你能接受这个不稳定窗口继续按下面的步骤操作。准备条件安装生成器插件go install github.com/grpc-ecosystem/grpc-gateway/v2/protoc-gen-openapiv3latest你的 proto 文件需要同时导入两个 Google API 定义文件annotations.proto用于 HTTP 绑定visibility.proto用于可见性标注import google/api/annotations.proto; import google/api/visibility.proto;proto 中至少有一个带 HTTP 绑定的 service。生成器会为每个声明了 HTTP 绑定的 proto 文件输出一份 OpenAPI JSONfoo.proto→foo.openapi.json没有 HTTP 绑定 service 的文件不产生输出。给元素打 INTERNAL / PREVIEW 标注可见性标注使用google.api.VisibilityRule可以加在 service、method、field 和枚举值上。仓库示例 proto 展示了完整的用法摘自 examples/internal/proto/examplepb/visibility_rule_echo_service.protosyntax proto3; package grpc.gateway.examples.internal.proto.examplepb; import google/api/annotations.proto; import google/api/visibility.proto; // SimpleMessage represents a simple message sent to the Echo service. message VisibilityRuleSimpleMessage { enum VisibilityEnum { VISIBILITY_ENUM_UNSPECIFIED 0; VISIBILITY_ENUM_VISIBLE 1; VISIBILITY_ENUM_INTERNAL 2 [(google.api.value_visibility).restriction INTERNAL]; VISIBILITY_ENUM_PREVIEW 3 [(google.api.value_visibility).restriction INTERNAL,PREVIEW]; } // Id represents the message identifier. string id 1; string internal_field 8 [(google.api.field_visibility).restriction INTERNAL]; string preview_field 9 [(google.api.field_visibility).restriction INTERNAL,PREVIEW]; VisibilityEnum an_enum 10; } service VisibilityRuleEchoService { // Echo method receives a simple message and returns it. // It should always be visible in the open API output. rpc Echo(VisibilityRuleSimpleMessage) returns (VisibilityRuleSimpleMessage) { option (google.api.http) {post: /v1/example/echo/{id}}; } // EchoInternal is an internal API that should only be visible in the OpenAPI spec // if visibility_restriction_selectors includes INTERNAL. rpc EchoInternal(VisibilityRuleSimpleMessage) returns (VisibilityRuleSimpleMessage) { option (google.api.method_visibility).restriction INTERNAL; option (google.api.http) {get: /v1/example/echo_internal}; } } // VisibilityRuleInternalEchoService service responds to incoming echo requests. // It should only be visible in the OpenAPI spec if visibility_restriction_selectors includes INTERNAL. service VisibilityRuleInternalEchoService { option (google.api.api_visibility).restriction INTERNAL; // Echo method receives a simple message and returns it. // It should not be visible in the open API output. rpc Echo(VisibilityRuleSimpleMessage) returns (VisibilityRuleSimpleMessage) { option (google.api.http) {post: /v1/example/internal/echo/{id}}; } }四个标注入口分别对应不同粒度字段[(google.api.field_visibility).restriction INTERNAL]方法option (google.api.method_visibility).restriction INTERNAL;整个服务option (google.api.api_visibility).restriction INTERNAL;枚举值[(google.api.value_visibility).restriction INTERNAL]。restriction 的标签取值是任意的INTERNAL和PREVIEW只是约定俗成的组合ALPHA、BETA、RELEASED等都可以只要 proto 注解和生成器选项用同一套词汇即可。restriction 也可以写多个标签逗号分隔如示例中的INTERNAL,PREVIEW表示该元素在两个标签任一被选中时都会出现。生成 OpenAPI 3.1 并隐藏 INTERNAL / PREVIEW 元素隐藏逻辑的核心规则是带VisibilityRule标注的元素只有当其 restriction 标签与配置的visibility_restriction_selectors有交集时才会保留没有标注的元素始终输出。所以要让INTERNAL/PREVIEW标注的元素不进入文档最直接的做法就是生成时不传这两个 selector。buf 方式主路径。buf.gen.yaml中只配置插件本身不加visibility_restriction_selectorsversion: v2 plugins: - local: protoc-gen-openapiv3 out: .然后运行buf generate。每个声明了 HTTP 绑定的 proto 文件旁边会出现对应的.openapi.json文件。protoc 方式。等价的命令protoc -I. \ --openapiv3_out. \ path/to/your/service.proto可选分支部分保留。如果你希望对外文档保留PREVIEW元素但只隐藏INTERNAL元素只配置一个 selector 即可例如 bufversion: v2 plugins: - local: protoc-gen-openapiv3 out: . opt: - visibility_restriction_selectorsPREVIEW或 protocprotoc -I. \ --openapiv3_out. \ --openapiv3_optvisibility_restriction_selectorsPREVIEW \ path/to/your/service.proto这个配置下标注为INTERNAL,PREVIEW的元素如示例中的EchoInternalAndPreview方法、preview_field字段会保留而只标注INTERNAL的元素被丢弃。反过来若同时声明两个 selector文档给出的多 selector 写法是多个opt条目opt: - visibility_restriction_selectorsPREVIEW - visibility_restriction_selectorsINTERNALINTERNAL和PREVIEW标注的元素就都会进入输出。selector 的增减直接决定哪些标注元素可见用同一套词汇即可。验证隐藏效果对生成的.openapi.json逐项核对以下行为它们均由文档明确定义普通元素无标注的 service、方法、字段、枚举值照常出现示例中的Echo方法、id字段。被隐藏的方法/v1/example/echo_internal对应的 operation 不应出现在paths中。被隐藏的服务整服务隐藏时其所有方法一并消失且该服务的 tag 从tags[]中省略。被隐藏的字段internalField、previewFieldJSON 命名不应出现在请求/响应 schema 的 properties 中。oneof 组当某个oneof组的字段全部被隐藏时该组 at most one set 约束一并被移除而不是留下空约束。枚举某个枚举值被隐藏后schema 的enum列表中不再出现该值如果枚举的所有值都被隐藏组件 schema 仍会输出可见字段可能引用它但退化为无约束的type: string此时生成器会写一行日志提示——看到这个日志就说明存在全隐藏的枚举需要放宽 selector 或隐藏引用它的字段。两条容易踩坑的规则要提前知道用作 HTTP 路径参数的字段上的可见性标注会被忽略——path template 本身始终暴露参数名。要隐藏一个接收受限输入的 operation应把google.api.method_visibility加在方法上或整服务用google.api.api_visibility而不是标注 path 字段。输出是确定的paths 按 RPC 声明顺序输出组件 schema 按字母排序响应码先默认后排序。因此可以用两次生成结果对比的方式验证 selector 变更确实影响了输出。文档还给出了一个端到端参考examples/internal/integration/openapiv3 展示了一个真实 grpc-gateway 跑在生成客户端后面的集成示例最小输出的对照样例见 protoc-gen-openapiv3/internal/genopenapi/testdata/simple_echo.openapi.json。边界与限制protoc-gen-openapiv3不消费grpc.gateway.protoc_gen_openapiv2.options注解集依赖 v2 那套注解标题、文档元信息等时要继续用protoc-gen-openapiv2。生成器不支持 YAML 输出只产出 JSON枚举一律按字符串渲染组件名固定为去掉前导点的完整 proto 全限定名如lib.v1.Book。由于是 Alpha 输出oneof、wrapper 类型、枚举、path-template 展开的编码规则可能随版本变化锁定版本后再进生产流程。可见性逻辑的实现入口是 protoc-gen-openapiv3/internal/genopenapi/visibility.goisVisible函数即restriction 标签与 selector 求交集这一判断的实现行为与上文一致。【免费下载链接】grpc-gatewaygRPC to JSON proxy generator following the gRPC HTTP spec项目地址: https://gitcode.com/GitHub_Trending/gr/grpc-gateway创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考