如何在protoc生成OpenAPIv3时忽略指定服务和消息

由于gnostic的protoc-gen-openapi不支持原OpenAPIv2使用的google.api.api_visibility选项，你可以通过以下两种方式实现忽略指定服务、方法的需求：

1. 使用gnostic自带的可见性扩展 #

gnostic提供了专属的扩展字段来控制服务和方法的生成，先在proto文件中引入对应的定义：

import "gnostic/openapi/v3/annotations.proto";

之后在目标服务或方法上添加gnostic.openapi.v3.visibility选项，设为INTERNAL即可跳过生成：

service WordValidator {
  option (gnostic.openapi.v3.visibility) = INTERNAL; // 忽略整个服务

  rpc Validate(ValidateRequest) returns (ValidateResponse) {
    option (gnostic.openapi.v3.visibility) = INTERNAL; // 仅忽略该方法
    option (google.api.http) = {
      post: "/v1/validate/{word}"
      body: "*"
    };
  }
}

2. 通过命令行参数过滤 #

如果不想修改proto文件，可在执行protoc命令时，给openapi_out参数指定包含或排除的服务：

• 仅生成指定服务：

protoc --openapi_out=services=TargetService1,TargetService2:../go/webserver/openapi {proto_files}

• 排除指定服务：

protoc --openapi_out=exclude_services=WordValidator:../go/webserver/openapi {proto_files}

关于忽略消息类型 #

gnostic的protoc-gen-openapi目前没有直接的扩展选项来单独忽略消息类型，但可以通过以下方式间接处理：

• 如果消息仅被已忽略的服务/方法使用，那么服务/方法被排除后，这些消息也不会出现在OpenAPI文档中
• 如果消息被其他服务引用但仍需忽略，可手动修改生成后的OpenAPI yaml/json文件，或编写简单脚本做后置清理

内容的提问来源于stack exchange，提问作者zipzapzoop45