1syntax = "proto3";
2
3// Visibility Rule Echo Service
4// Similar to echo_service.proto but with annotations to change visibility
5// of services, methods, fields and enum values.
6//
7// `google.api.VisibilityRule` annotations are added to customize where they are generated.
8// Combined with the option `visibility_restriction_selectors` overlapping rules will appear in the OpenAPI output.
9// Elements without `google.api.VisibilityRule` annotations will appear as usual in the generated output.
10//
11// These restrictions and selectors are completely arbitrary and you can define whatever values or hierarchies you want.
12// In this example `INTERNAL`, `PREVIEW` are used, but `INTERNAL`, `ALPHA`, `BETA`, `RELEASED`, or anything else could be used if you wish.
13package grpc.gateway.examples.internal.proto.examplepb;
14
15import "google/api/annotations.proto";
16import "google/api/visibility.proto";
17
18option go_package = "github.com/grpc-ecosystem/grpc-gateway/v2/examples/internal/proto/examplepb;examplepb";
19
20// Embedded represents a message embedded in SimpleMessage.
21message VisibilityRuleEmbedded {
22 oneof mark {
23 int64 progress = 1;
24 string note = 2;
25 string internal_field = 3 [(google.api.field_visibility).restriction = "INTERNAL"];
26 string preview_field = 4 [(google.api.field_visibility).restriction = "INTERNAL,PREVIEW"];
27 }
28}
29
30// SimpleMessage represents a simple message sent to the Echo service.
31message VisibilityRuleSimpleMessage {
32 enum VisibilityEnum {
33 VISIBILITY_ENUM_UNSPECIFIED = 0;
34 VISIBILITY_ENUM_VISIBLE = 1;
35 VISIBILITY_ENUM_INTERNAL = 2 [(google.api.value_visibility).restriction = "INTERNAL"];
36 VISIBILITY_ENUM_PREVIEW = 3 [(google.api.value_visibility).restriction = "INTERNAL,PREVIEW"];
37 }
38
39 // Id represents the message identifier.
40 string id = 1;
41 int64 num = 2;
42 oneof code {
43 int64 line_num = 3;
44 string lang = 4;
45 }
46 VisibilityRuleEmbedded status = 5;
47 oneof ext {
48 int64 en = 6;
49 VisibilityRuleEmbedded no = 7;
50 }
51 string internal_field = 8 [(google.api.field_visibility).restriction = "INTERNAL"];
52 string preview_field = 9 [(google.api.field_visibility).restriction = "INTERNAL,PREVIEW"];
53 VisibilityEnum an_enum = 10;
54}
55
56// MessageInPreviewMethod doesn't define its own visibility restrictions,
57// but is only included in a method marked as "PREVIEW", so it will only
58// appear if `visibility_restriction_selectors` include "PREVIEW".
59message VisibilityRuleMessageInPreviewMethod {
60 string id = 1;
61 VisibilityRuleSubMessageInPreviewMethod sub_message = 2;
62 VisibilityRuleEnumInPreviewMethod enum = 3;
63}
64
65// SubMessageInPreviewMethod doesn't define its own visibility restrictions,
66// but is only included in a method marked as "PREVIEW", so it will only
67// appear if `visibility_restriction_selectors` include "PREVIEW".
68message VisibilityRuleSubMessageInPreviewMethod {
69 string id = 1;
70}
71
72// EnumInPreviewMethod doesn't define its own visibility restrictions,
73// but is only included in a method marked as "PREVIEW", so it will only
74// appear if `visibility_restriction_selectors` include "PREVIEW".
75enum VisibilityRuleEnumInPreviewMethod {
76 VISIBILITY_RULE_ENUM_IN_PREVIEW_METHOD_UNSPECIFIED = 0;
77}
78
79// VisibilityRuleEchoService service responds to incoming echo requests.
80// Different services will be available in the swagger documentation depending
81// based on `google.api.VisibilityRule`s and the set `visibility_restriction_selectors`
82// flag when calling protoc-gen-openapiv2.
83service VisibilityRuleEchoService {
84 // Echo method receives a simple message and returns it.
85 // It should always be visible in the open API output.
86 rpc Echo(VisibilityRuleSimpleMessage) returns (VisibilityRuleSimpleMessage) {
87 option (google.api.http) = {post: "/v1/example/echo/{id}"};
88 }
89 // EchoInternal is an internal API that should only be visible in the OpenAPI spec
90 // if `visibility_restriction_selectors` includes "INTERNAL".
91 rpc EchoInternal(VisibilityRuleSimpleMessage) returns (VisibilityRuleSimpleMessage) {
92 option (google.api.method_visibility).restriction = "INTERNAL";
93 option (google.api.http) = {get: "/v1/example/echo_internal"};
94 }
95 // EchoPreview is a preview API that should only be visible in the OpenAPI spec
96 // if `visibility_restriction_selectors` includes "PREVIEW".
97 rpc EchoPreview(VisibilityRuleSimpleMessage) returns (VisibilityRuleMessageInPreviewMethod) {
98 option (google.api.method_visibility).restriction = "PREVIEW";
99 option (google.api.http) = {get: "/v1/example/echo_preview"};
100 }
101 // EchoInternalAndPreview is a internal and preview API that should only be visible in the OpenAPI spec
102 // if `visibility_restriction_selectors` includes "PREVIEW" or "INTERNAL".
103 rpc EchoInternalAndPreview(VisibilityRuleSimpleMessage) returns (VisibilityRuleSimpleMessage) {
104 option (google.api.method_visibility).restriction = "INTERNAL,PREVIEW";
105 option (google.api.http) = {get: "/v1/example/echo_internal_and_preview"};
106 }
107}
108
109// VisibilityRuleInternalEchoService service responds to incoming echo requests.
110// It should only be visible in the OpenAPI spec if `visibility_restriction_selectors` includes "INTERNAL".
111service VisibilityRuleInternalEchoService {
112 option (google.api.api_visibility).restriction = "INTERNAL";
113
114 // Echo method receives a simple message and returns it.
115 // It should not be visible in the open API output.
116 rpc Echo(VisibilityRuleSimpleMessage) returns (VisibilityRuleSimpleMessage) {
117 option (google.api.http) = {post: "/v1/example/internal/echo/{id}"};
118 }
119}
View as plain text