github.com/grpc-ecosystem/grpc-gateway/v2@v2.19.1/examples/internal/proto/examplepb/visibility_rule_echo_service.proto (about)

     1  syntax = "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.
    13  package grpc.gateway.examples.internal.proto.examplepb;
    14  
    15  import "google/api/annotations.proto";
    16  import "google/api/visibility.proto";
    17  
    18  option go_package = "github.com/grpc-ecosystem/grpc-gateway/v2/examples/internal/proto/examplepb;examplepb";
    19  
    20  // Embedded represents a message embedded in SimpleMessage.
    21  message 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.
    31  message 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".
    59  message 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".
    68  message 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".
    75  enum 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.
    83  service 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".
   111  service 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  }