Add remove_internal_comments option (#3560)

To allow internal comments within the protobuf which won't make
it the generated OAS file.

Using Google's AIP-192:

https://google.aip.dev/192#internal-comments

Author: same-id

Makefile

@@ -118,6 +118,9 @@ proto:
 	buf generate \
 		--template ./examples/internal/proto/examplepb/ignore_comment.buf.gen.yaml \
 		--path examples/internal/proto/examplepb/ignore_comment.proto
+	buf generate \
+		--template ./examples/internal/proto/examplepb/remove_internal_comment.buf.gen.yaml \
+		--path examples/internal/proto/examplepb/remove_internal_comment.proto
 	buf generate \
 		--template ./examples/internal/proto/examplepb/visibility_rule_preview_echo_service.buf.gen.yaml \
 		--path examples/internal/proto/examplepb/visibility_rule_echo_service.proto

buf.yaml

@@ -24,6 +24,7 @@ lint:
       - examples/internal/proto/examplepb/visibility_rule_echo_service.proto
       - examples/internal/proto/examplepb/use_go_template.proto
       - examples/internal/proto/examplepb/ignore_comment.proto
+      - examples/internal/proto/examplepb/remove_internal_comment.proto
       - examples/internal/proto/examplepb/wrappers.proto
     ENUM_VALUE_PREFIX:
       - examples/internal/proto/examplepb/a_bit_of_everything.proto
@@ -61,6 +62,7 @@ lint:
       - examples/internal/proto/examplepb/visibility_rule_echo_service.proto
       - examples/internal/proto/examplepb/use_go_template.proto
       - examples/internal/proto/examplepb/ignore_comment.proto
+      - examples/internal/proto/examplepb/remove_internal_comment.proto
       - examples/internal/proto/examplepb/wrappers.proto
       - examples/internal/proto/oneofenum/oneof_enum.proto
       - examples/internal/proto/pathenum/path_enum.proto
@@ -87,6 +89,7 @@ lint:
       - examples/internal/proto/examplepb/visibility_rule_echo_service.proto
       - examples/internal/proto/examplepb/use_go_template.proto
       - examples/internal/proto/examplepb/ignore_comment.proto
+      - examples/internal/proto/examplepb/remove_internal_comment.proto
       - examples/internal/proto/examplepb/wrappers.proto
       - runtime/internal/examplepb/example.proto
       - runtime/internal/examplepb/non_standard_names.proto
@@ -108,6 +111,7 @@ lint:
       - examples/internal/proto/examplepb/visibility_rule_echo_service.proto
       - examples/internal/proto/examplepb/use_go_template.proto
       - examples/internal/proto/examplepb/ignore_comment.proto
+      - examples/internal/proto/examplepb/remove_internal_comment.proto
       - examples/internal/proto/examplepb/wrappers.proto
       - examples/internal/proto/oneofenum/oneof_enum.proto
       - examples/internal/proto/pathenum/path_enum.proto
@@ -166,6 +170,7 @@ lint:
       - examples/internal/proto/examplepb/visibility_rule_echo_service.proto
       - examples/internal/proto/examplepb/use_go_template.proto
       - examples/internal/proto/examplepb/ignore_comment.proto
+      - examples/internal/proto/examplepb/remove_internal_comment.proto
       - examples/internal/proto/examplepb/wrappers.proto
       - runtime/internal/examplepb/non_standard_names.proto
     SERVICE_PASCAL_CASE:

docs/docs/mapping/customizing_openapi_output.md

@@ -847,6 +847,11 @@ or with `protoc`:
 protoc --openapiv2_out=. --openapiv2_opt=ignore_comments=true ./path/to/file.proto
 ```
 
+### Removing internal comments
+
+If you want to remove internal comments from the from OpenAPI output (such as `TODO` and `FIXME` directives) you can use the `remove_internal_comments` option.
+If set to `true`, this will remove all comment text located between `(--` and `--)` as per [AIP 192: Internal comments](https://google.aip.dev/192#internal-comments).
+
 ### Preserve RPC Path Order
 
 By default, generated Swagger files emit paths found in proto files in alphabetical order. If you would like to 

examples/internal/proto/examplepb/BUILD.bazel

@@ -25,6 +25,7 @@ package(default_visibility = ["//visibility:public"])
 # gazelle:exclude use_go_template.pb.gw.go
 # gazelle:exclude use_go_template_grpc.pb.go
 # gazelle:exclude ignore_comment.pb.gw.go
+# gazelle:exclude remove_internal_comment.pb.gw.go
 # gazelle:exclude ignore_comment_grpc.pb.go
 # gazelle:exclude wrappers.pb.gw.go
 # gazelle:exclude wrappers_grpc.pb.go
@@ -53,6 +54,7 @@ proto_library(
         "generated_output.proto",
         "ignore_comment.proto",
         "non_standard_names.proto",
+        "remove_internal_comment.proto",
         "response_body_service.proto",
         "stream.proto",
         "unannotated_echo_service.proto",

examples/internal/proto/examplepb/remove_internal_comment.buf.gen.yaml

@@ -0,0 +1,6 @@
+version: v1
+plugins:
+  - name: openapiv2
+    out: .
+    opt:
+      - remove_internal_comments=true