feat: add allowed-visibilities option (#192)

sudorandom · web-flow · commit 9c3c9d1c8547 · 2026-01-18T15:40:57.000+01:00
diff --git a/README.md b/README.md
@@ -176,6 +176,7 @@ protoc-gen-connect-openapi also has support for the [OpenAPI v3 annotations](htt
 | path                       | `{filepath}` | Output filepath, defaults to per-proto file output if not given.  When using [buf](https://github.com/bufbuild/buf), generating multiple files to the same path requires additional configuration to avoid overwriting files. See [#159](https://github.com/sudorandom/protoc-gen-connect-openapi/issues/159).                                                                            |
 | path-prefix                | `{path}` | Prefixes the given string to the beginning of each HTTP path.                                                                                               |
 | features                   | `{feature1};{feature2};[...]` | Semicolon-separated list of features to enable. Options: `connectrpc`, `google.api.http`, `twirp`, `gnostic`, `protovalidate`; Default: `connectrpc;google.api.http;gnostic;protovalidate`. If this option is used, only the specified features will be enabled. |
+| allowed-visibilities   | `{visibility1};{visibility2};[...]` | Semicolon-separated list of visibility labels to include. If an element (service, method, message, enum, enum value, or field) has a `google.api.visibility` rule, it will only be included in the generated OpenAPI specification if its visibility label is in this list. If this option is omitted, all elements are included regardless of their visibility. |
 | proto                      | - | Generate requests/responses with the protobuf content type                                                                                                         |
 | services                   | `{service_name}` | Specifies which services to include in the generated OpenAPI specification. If omitted, all services are included. The service name must be fully qualified (e.g., "package.name.ServiceName"). Wildcards (`*` and `**`) are supported; `*` matches a single package segment, while `**` matches multiple. This option can be provided multiple times to include multiple services.  |
 | short-operation-ids        | - | Set the operationId to shortServiceName + "_" + method short name instead of the full method name.                                                                 |
diff --git a/internal/converter/converter.go b/internal/converter/converter.go
@@ -26,6 +26,7 @@ import (
 	"github.com/sudorandom/protoc-gen-connect-openapi/internal/converter/gnostic"
 	"github.com/sudorandom/protoc-gen-connect-openapi/internal/converter/options"
 	"github.com/sudorandom/protoc-gen-connect-openapi/internal/converter/util"
+	"github.com/sudorandom/protoc-gen-connect-openapi/internal/converter/visibility"
 )
 
 func ConvertFrom(rd io.Reader) (*pluginpb.CodeGeneratorResponse, error) {
@@ -286,13 +287,21 @@ func appendToSpec(opts options.Options, spec *v3.Document, fd protoreflect.FileD
 		// Files can have enums
 		enums := fd.Enums()
 		for i := 0; i < enums.Len(); i++ {
-			AddEnumToSchema(opts, enums.Get(i), spec)
+			enum := enums.Get(i)
+			if visibility.ShouldBeFiltered(visibility.GetVisibilityRule(enum), opts.AllowedVisibilities) {
+				continue
+			}
+			AddEnumToSchema(opts, enum, spec)
 		}
 
 		// Files can have messages
 		messages := fd.Messages()
 		for i := 0; i < messages.Len(); i++ {
-			AddMessageSchemas(opts, messages.Get(i), spec)
+			message := messages.Get(i)
+			if visibility.ShouldBeFiltered(visibility.GetVisibilityRule(message), opts.AllowedVisibilities) {
+				continue
+			}
+			AddMessageSchemas(opts, message, spec)
 		}
 	}
 
@@ -338,6 +347,11 @@ func appendServiceDocs(opts options.Options, spec *v3.Document, fd protoreflect.
 		if !opts.HasService(service.FullName()) {
 			continue
 		}
+		// Add visibility filtering for services
+		if visibility.ShouldBeFiltered(visibility.GetVisibilityRule(service), opts.AllowedVisibilities) {
+			opts.Logger.Debug("Filtering service due to visibility", slog.String("service", string(service.FullName())), slog.Any("restriction_selectors", opts.AllowedVisibilities))
+			continue
+		}
 
 		builder.WriteString("## ")
 		builder.WriteString(string(service.FullName()))
diff --git a/internal/converter/converter_test.go b/internal/converter/converter_test.go
@@ -39,6 +39,7 @@ var scenarios = []Scenario{
 	{Name: "with_google_error_detail", Options: "with-google-error-detail"},
 	{Name: "twirp", Options: "features=google.api.http;twirp;gnostic;protovalidate"},
 	{Name: "twirp_only", Options: "features=twirp"},
+	{Name: "visibility", Options: "features=google.api.http;gnostic;protovalidate,allowed-visibilities=INTERNAL;PREVIEW"},
 	{Name: "disable_default_response", Options: "disable-default-response"},
 }
 
diff --git a/internal/converter/options/options.go b/internal/converter/options/options.go
@@ -73,6 +73,8 @@ type Options struct {
 	DisableDefaultResponse bool
 	// EnabledFeatures is a map of enabled features.
 	EnabledFeatures map[Feature]bool
+	// AllowedVisibilities is a map of visibility strings to include. If an element has a `google.api.visibility` rule with a `restriction` that is not in this map, it will be excluded.
+	AllowedVisibilities map[string]bool
 
 	MessageAnnotator        MessageAnnotator
 	FieldAnnotator          FieldAnnotator
@@ -253,6 +255,12 @@ func FromString(s string) (Options, error) {
 				return opts, err
 			}
 			opts.Services = append(opts.Services, patterns...)
+		case strings.HasPrefix(param, "allowed-visibilities="):
+			selectors := strings.Split(param[len("allowed-visibilities="):], ";")
+			opts.AllowedVisibilities = make(map[string]bool)
+			for _, selector := range selectors {
+				opts.AllowedVisibilities[selector] = true
+			}
 		default:
 			return opts, fmt.Errorf("invalid parameter: %s", param)
 		}
diff --git a/internal/converter/paths.go b/internal/converter/paths.go
@@ -1,6 +1,8 @@
 package converter
 
 import (
+	"log/slog"
+
 	v3 "github.com/pb33f/libopenapi/datamodel/high/v3"
 	"github.com/pb33f/libopenapi/orderedmap"
 	"github.com/sudorandom/protoc-gen-connect-openapi/internal/converter/connectrpc"
@@ -9,6 +11,7 @@ import (
 	"github.com/sudorandom/protoc-gen-connect-openapi/internal/converter/options"
 	"github.com/sudorandom/protoc-gen-connect-openapi/internal/converter/twirp"
 	"github.com/sudorandom/protoc-gen-connect-openapi/internal/converter/util"
+	"github.com/sudorandom/protoc-gen-connect-openapi/internal/converter/visibility"
 	"google.golang.org/protobuf/reflect/protoreflect"
 )
 
@@ -23,6 +26,11 @@ func addPathItemsFromFile(opts options.Options, fd protoreflect.FileDescriptor,
 		for j := 0; j < methods.Len(); j++ {
 			method := methods.Get(j)
 
+			if visibility.ShouldBeFiltered(visibility.GetVisibilityRule(method), opts.AllowedVisibilities) {
+				opts.Logger.Debug("Filtering method due to visibility", slog.String("method", string(method.FullName())), slog.Any("restriction_selectors", opts.AllowedVisibilities))
+				continue
+			}
+
 			// No matter what, we add the schemas for the method input/output
 			AddMessageSchemas(opts, method.Input(), doc)
 			AddMessageSchemas(opts, method.Output(), doc)
@@ -73,7 +81,6 @@ func addPathItemsFromFile(opts options.Options, fd protoreflect.FileDescriptor,
 
 	return nil
 }
-
 func mergePathItems(existing, new *v3.PathItem) {
 	// Merge operations
 	operations := []struct {
diff --git a/internal/converter/schema.go b/internal/converter/schema.go
@@ -13,12 +13,17 @@ import (
 	"github.com/sudorandom/protoc-gen-connect-openapi/internal/converter/options"
 	"github.com/sudorandom/protoc-gen-connect-openapi/internal/converter/schema"
 	"github.com/sudorandom/protoc-gen-connect-openapi/internal/converter/util"
+	"github.com/sudorandom/protoc-gen-connect-openapi/internal/converter/visibility"
 )
 
 func AddMessageSchemas(opts options.Options, md protoreflect.MessageDescriptor, doc *v3.Document) {
 	if md == nil {
 		return
 	}
+	if visibility.ShouldBeFiltered(visibility.GetVisibilityRule(md), opts.AllowedVisibilities) {
+		opts.Logger.Debug("Filtering message due to visibility", slog.String("message", string(md.FullName())), slog.Any("restriction_selectors", opts.AllowedVisibilities))
+		return
+	}
 	if _, ok := doc.Components.Schemas.Get(string(md.FullName())); ok {
 		return
 	}
@@ -60,6 +65,10 @@ func AddEnumToSchema(opts options.Options, ed protoreflect.EnumDescriptor, doc *
 	if ed == nil {
 		return
 	}
+	if visibility.ShouldBeFiltered(visibility.GetVisibilityRule(ed), opts.AllowedVisibilities) {
+		opts.Logger.Debug("Filtering enum due to visibility", slog.String("enum", string(ed.FullName())), slog.Any("restriction_selectors", opts.AllowedVisibilities))
+		return
+	}
 	if _, ok := doc.Components.Schemas.Get(string(ed.FullName())); ok {
 		return
 	}
@@ -75,6 +84,10 @@ func enumToSchema(opts options.Options, tt protoreflect.EnumDescriptor) (string,
 	values := tt.Values()
 	for i := 0; i < values.Len(); i++ {
 		value := values.Get(i)
+		if visibility.ShouldBeFiltered(visibility.GetVisibilityRule(value), opts.AllowedVisibilities) {
+			opts.Logger.Debug("Filtering enum value due to visibility", slog.String("enum_value", string(value.FullName())), slog.Any("restriction_selectors", opts.AllowedVisibilities))
+			continue // Skip this enum value
+		}
 		children = append(children, utils.CreateStringNode(string(value.Name())))
 		if opts.IncludeNumberEnumValues {
 			children = append(children, utils.CreateIntNode(strconv.FormatInt(int64(value.Number()), 10)))
diff --git a/internal/converter/schema/schema.go b/internal/converter/schema/schema.go
@@ -11,6 +11,7 @@ import (
 	"github.com/pb33f/libopenapi/utils"
 	"github.com/sudorandom/protoc-gen-connect-openapi/internal/converter/options"
 	"github.com/sudorandom/protoc-gen-connect-openapi/internal/converter/util"
+	"github.com/sudorandom/protoc-gen-connect-openapi/internal/converter/visibility"
 	"go.yaml.in/yaml/v4"
 	"google.golang.org/protobuf/reflect/protoreflect"
 )
@@ -42,6 +43,10 @@ func MessageToSchema(opts options.Options, tt protoreflect.MessageDescriptor) (s
 	fields := tt.Fields()
 	for i := 0; i < fields.Len(); i++ {
 		field := fields.Get(i)
+		if visibility.ShouldBeFiltered(visibility.GetVisibilityRule(field), opts.AllowedVisibilities) {
+			opts.Logger.Debug("Filtering field due to visibility", slog.String("field", string(field.FullName())), slog.Any("restriction_selectors", opts.AllowedVisibilities))
+			continue
+		}
 		if oneOf := field.ContainingOneof(); oneOf != nil && !oneOf.IsSynthetic() {
 			oneOneGroups[oneOf.FullName()] = append(oneOneGroups[oneOf.FullName()], field)
 			continue
diff --git a/internal/converter/testdata/fileset.binpb b/internal/converter/testdata/fileset.binpb
diff --git a/internal/converter/testdata/visibility/output/visibility.openapi.json b/internal/converter/testdata/visibility/output/visibility.openapi.json
@@ -0,0 +1,84 @@
+{
+  "openapi": "3.1.0",
+  "info": {
+    "title": "visibility"
+  },
+  "paths": {
+    "/v1/messages/{message_id}": {
+      "get": {
+        "tags": [
+          "visibility.VisibilityService"
+        ],
+        "summary": "GetMessage",
+        "operationId": "visibility.VisibilityService.GetMessage",
+        "parameters": [
+          {
+            "name": "message_id",
+            "in": "path",
+            "required": true,
+            "schema": {
+              "type": "string",
+              "title": "message_id"
+            }
+          }
+        ],
+        "responses": {
+          "200": {
+            "description": "Success",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/visibility.Message"
+                }
+              }
+            }
+          }
+        }
+      }
+    }
+  },
+  "components": {
+    "schemas": {
+      "visibility.GetMessageRequest": {
+        "type": "object",
+        "properties": {
+          "messageId": {
+            "type": "string",
+            "title": "message_id"
+          }
+        },
+        "title": "GetMessageRequest",
+        "additionalProperties": false
+      },
+      "visibility.Message": {
+        "type": "object",
+        "properties": {
+          "publicField": {
+            "type": "string",
+            "title": "public_field"
+          },
+          "internalField": {
+            "type": "string",
+            "title": "internal_field"
+          },
+          "previewField": {
+            "type": "string",
+            "title": "preview_field"
+          },
+          "anotherPublicField": {
+            "type": "string",
+            "title": "another_public_field"
+          }
+        },
+        "title": "Message",
+        "additionalProperties": false
+      }
+    }
+  },
+  "security": [],
+  "tags": [
+    {
+      "name": "visibility.VisibilityService"
+    }
+  ]
+}
diff --git a/internal/converter/testdata/visibility/output/visibility.openapi.yaml b/internal/converter/testdata/visibility/output/visibility.openapi.yaml
@@ -0,0 +1,54 @@
+openapi: 3.1.0
+info:
+  title: visibility
+paths:
+  /v1/messages/{message_id}:
+    get:
+      tags:
+        - visibility.VisibilityService
+      summary: GetMessage
+      operationId: visibility.VisibilityService.GetMessage
+      parameters:
+        - name: message_id
+          in: path
+          required: true
+          schema:
+            type: string
+            title: message_id
+      responses:
+        "200":
+          description: Success
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/visibility.Message'
+components:
+  schemas:
+    visibility.GetMessageRequest:
+      type: object
+      properties:
+        messageId:
+          type: string
+          title: message_id
+      title: GetMessageRequest
+      additionalProperties: false
+    visibility.Message:
+      type: object
+      properties:
+        publicField:
+          type: string
+          title: public_field
+        internalField:
+          type: string
+          title: internal_field
+        previewField:
+          type: string
+          title: preview_field
+        anotherPublicField:
+          type: string
+          title: another_public_field
+      title: Message
+      additionalProperties: false
+security: []
+tags:
+  - name: visibility.VisibilityService
diff --git a/internal/converter/testdata/visibility/visibility.proto b/internal/converter/testdata/visibility/visibility.proto
@@ -0,0 +1,27 @@
+syntax = "proto3";
+
+package visibility;
+
+import "google/api/annotations.proto";
+import "google/api/visibility.proto";
+
+option go_package = "github.com/sudorandom/protoc-gen-connect-openapi/internal/converter/testdata/visibility";
+
+service VisibilityService {
+  rpc GetMessage(GetMessageRequest) returns (Message) {
+    option (google.api.http) = {
+      get: "/v1/messages/{message_id}"
+    };
+  }
+}
+
+message GetMessageRequest {
+  string message_id = 1;
+}
+
+message Message {
+  string public_field = 1;
+  string internal_field = 2 [(google.api.field_visibility).restriction = "INTERNAL"];
+  string preview_field = 3 [(google.api.field_visibility).restriction = "PREVIEW"];
+  string another_public_field = 4;
+}
diff --git a/internal/converter/visibility/visibility.go b/internal/converter/visibility/visibility.go

Original file line number	Diff line number	Diff line change
`@@ -39,6 +39,7 @@ var scenarios = []Scenario{`
`39`	`39`	`{Name: "with_google_error_detail", Options: "with-google-error-detail"},`
`40`	`40`	`{Name: "twirp", Options: "features=google.api.http;twirp;gnostic;protovalidate"},`
`41`	`41`	`{Name: "twirp_only", Options: "features=twirp"},`
	`42`	`+ {Name: "visibility", Options: "features=google.api.http;gnostic;protovalidate,allowed-visibilities=INTERNAL;PREVIEW"},`
`42`	`43`	`{Name: "disable_default_response", Options: "disable-default-response"},`
`43`	`44`	`}`
`44`	`45`