...

Text file src/github.com/grpc-ecosystem/grpc-gateway/examples/internal/proto/examplepb/a_bit_of_everything.proto

Documentation: github.com/grpc-ecosystem/grpc-gateway/examples/internal/proto/examplepb

     1syntax = "proto3";
     2option go_package = "examplepb";
     3package grpc.gateway.examples.internal.examplepb;
     4
     5import "google/api/annotations.proto";
     6import "google/protobuf/field_mask.proto";
     7import "google/protobuf/empty.proto";
     8import "google/protobuf/duration.proto";
     9import "google/protobuf/wrappers.proto";
    10import "examples/internal/proto/pathenum/path_enum.proto";
    11import "examples/internal/proto/sub/message.proto";
    12import "examples/internal/proto/sub2/message.proto";
    13import "google/protobuf/timestamp.proto";
    14import "protoc-gen-swagger/options/annotations.proto";
    15
    16option (grpc.gateway.protoc_gen_swagger.options.openapiv2_swagger) = {
    17	info: {
    18		title: "A Bit of Everything";
    19		version: "1.0";
    20		contact: {
    21			name: "gRPC-Gateway project";
    22			url: "https://github.com/grpc-ecosystem/grpc-gateway";
    23			email: "none@example.com";
    24		};
    25		license: {
    26			name: "BSD 3-Clause License";
    27			url: "https://github.com/grpc-ecosystem/grpc-gateway/blob/master/LICENSE.txt";
    28		};
    29		extensions: {
    30			key: "x-something-something";
    31			value {
    32				string_value: "yadda";
    33			}
    34		}
    35	};
    36	// Overwriting host entry breaks tests, so this is not done here.
    37	external_docs: {
    38		url: "https://github.com/grpc-ecosystem/grpc-gateway";
    39		description: "More about gRPC-Gateway";
    40	}
    41	schemes: HTTP;
    42	schemes: HTTPS;
    43	schemes: WSS;
    44	consumes: "application/json";
    45	consumes: "application/x-foo-mime";
    46	produces: "application/json";
    47	produces: "application/x-foo-mime";
    48	security_definitions: {
    49		security: {
    50			key: "BasicAuth";
    51			value: {
    52				type: TYPE_BASIC;
    53			}
    54		}
    55		security: {
    56			key: "ApiKeyAuth";
    57			value: {
    58				type: TYPE_API_KEY;
    59				in: IN_HEADER;
    60				name: "X-API-Key";
    61				extensions: {
    62					key: "x-amazon-apigateway-authtype";
    63					value {
    64						string_value: "oauth2";
    65					}
    66				}
    67				extensions: {
    68					key: "x-amazon-apigateway-authorizer";
    69					value {
    70						struct_value {
    71							fields {
    72								key: "type";
    73								value {
    74									string_value: "token";
    75								}
    76							}
    77							fields {
    78								key: "authorizerResultTtlInSeconds";
    79								value {
    80									number_value: 60;
    81								}
    82							}
    83						}
    84					}
    85				}
    86			}
    87		}
    88		security: {
    89			key: "OAuth2";
    90			value: {
    91				type: TYPE_OAUTH2;
    92				flow: FLOW_ACCESS_CODE;
    93				authorization_url: "https://example.com/oauth/authorize";
    94				token_url: "https://example.com/oauth/token";
    95				scopes: {
    96					scope: {
    97						key: "read";
    98						value: "Grants read access";
    99					}
   100					scope: {
   101						key: "write";
   102						value: "Grants write access";
   103					}
   104					scope: {
   105						key: "admin";
   106						value: "Grants read and write access to administrative information";
   107					}
   108				}
   109			}
   110		}
   111	}
   112	security: {
   113		security_requirement: {
   114			key: "BasicAuth";
   115			value: {};
   116		}
   117		security_requirement: {
   118			key: "ApiKeyAuth";
   119			value: {};
   120		}
   121	}
   122	security: {
   123		security_requirement: {
   124			key: "OAuth2";
   125			value: {
   126				scope: "read";
   127				scope: "write";
   128			}
   129		}
   130		security_requirement: {
   131			key: "ApiKeyAuth";
   132			value: {};
   133		}
   134	}
   135	responses: {
   136		key: "403";
   137		value: {
   138			description: "Returned when the user does not have permission to access the resource.";
   139		}
   140	}
   141	responses: {
   142		key: "404";
   143		value: {
   144			description: "Returned when the resource does not exist.";
   145			schema: {
   146				json_schema: {
   147					type: STRING;
   148				}
   149			}
   150		}
   151	}
   152	responses: {
   153		key: "418";
   154		value: {
   155			description: "I'm a teapot.";
   156			schema: {
   157				json_schema: {
   158					ref: ".grpc.gateway.examples.internal.examplepb.NumericEnum";
   159				}
   160			}
   161		}
   162	}
   163	responses: {
   164		key: "500";
   165		value: {
   166			description: "Server error";
   167			headers: {
   168				key: "X-Correlation-Id"
   169				value: {
   170					description: "Unique event identifier for server requests"
   171					type: "string"
   172					format: "uuid"
   173					default: "\"2438ac3c-37eb-4902-adef-ed16b4431030\""
   174					pattern: "^[0-9A-F]{8}-[0-9A-F]{4}-4[0-9A-F]{3}-[89AB][0-9A-F]{3}-[0-9A-F]{12}$"
   175				}
   176			};
   177			schema: {
   178				json_schema: {
   179					ref: ".grpc.gateway.examples.internal.examplepb.ErrorResponse";
   180				}
   181			}
   182		}
   183	}
   184	extensions: {
   185		key: "x-grpc-gateway-foo";
   186		value {
   187			string_value: "bar";
   188		}
   189	}
   190	extensions: {
   191		key: "x-grpc-gateway-baz-list";
   192		value {
   193			list_value: {
   194				values: {
   195					string_value: "one";
   196				}
   197				values: {
   198					bool_value: true;
   199				}
   200			}
   201		}
   202	}
   203};
   204
   205message ErrorResponse{
   206	string correlationId = 1 [(grpc.gateway.protoc_gen_swagger.options.openapiv2_field) = {
   207		pattern: "^[0-9A-F]{8}-[0-9A-F]{4}-4[0-9A-F]{3}-[89AB][0-9A-F]{3}-[0-9A-F]{12}$",
   208		title: "x-correlation-id",
   209		description: "Unique event identifier for server requests",
   210		format: "uuid",
   211		example: "\"2438ac3c-37eb-4902-adef-ed16b4431030\""
   212	}];
   213	ErrorObject error = 2;
   214}
   215
   216message ErrorObject{
   217	int32 code = 1 [(grpc.gateway.protoc_gen_swagger.options.openapiv2_field) = {
   218		pattern: "^[0-9]$",
   219		title: "code",
   220		description: "Response code",
   221		format: "integer"
   222	}];
   223	string message = 2 [(grpc.gateway.protoc_gen_swagger.options.openapiv2_field) = {
   224		pattern: "^[a-zA-Z0-9]{1, 32}$",
   225		title: "message",
   226		description: "Response message"
   227	}];
   228}
   229
   230
   231// Intentionally complicated message type to cover many features of Protobuf.
   232message ABitOfEverything {
   233	option (grpc.gateway.protoc_gen_swagger.options.openapiv2_schema) = {
   234		json_schema: {
   235			title: "A bit of everything"
   236			description: "Intentionaly complicated message type to cover many features of Protobuf."
   237			required: ["uuid", "int64_value", "double_value"]
   238		}
   239		external_docs: {
   240			url: "https://github.com/grpc-ecosystem/grpc-gateway";
   241			description: "Find out more about ABitOfEverything";
   242		}
   243		example_string: "{\"uuid\": \"0cf361e1-4b44-483d-a159-54dabdf7e814\"}"
   244	};
   245
   246	// Nested is nested type.
   247	message Nested {
   248		option (grpc.gateway.protoc_gen_swagger.options.openapiv2_schema) = {
   249			example_string: "{\"ok\": \"TRUE\"}"
   250		};
   251		// name is nested field.
   252		string name = 1;
   253		uint32 amount = 2;
   254		// DeepEnum is one or zero.
   255		enum DeepEnum {
   256			// FALSE is false.
   257			FALSE = 0;
   258			// TRUE is true.
   259			TRUE = 1;
   260		}
   261
   262		// DeepEnum comment.
   263		DeepEnum ok = 3 [(grpc.gateway.protoc_gen_swagger.options.openapiv2_field) = {description: "DeepEnum description."}];
   264	}
   265	Nested single_nested = 25;
   266
   267	string uuid = 1 [(grpc.gateway.protoc_gen_swagger.options.openapiv2_field) = {pattern: "[a-fA-F0-9]{8}-[a-fA-F0-9]{4}-[a-fA-F0-9]{4}-[a-fA-F0-9]{4}-[a-fA-F0-9]{12}", min_length: 1}];
   268	repeated Nested nested = 2;
   269	float float_value = 3 [(grpc.gateway.protoc_gen_swagger.options.openapiv2_field) = {description: "Float value field", default: "0.2", required: ['float_value']}];
   270	double double_value = 4;
   271	int64 int64_value = 5;
   272	uint64 uint64_value = 6;
   273	int32 int32_value = 7;
   274	fixed64 fixed64_value = 8;
   275	fixed32 fixed32_value = 9;
   276	bool bool_value = 10;
   277	string string_value = 11;
   278	bytes bytes_value = 29;
   279	uint32 uint32_value = 13;
   280	NumericEnum enum_value = 14;
   281	pathenum.PathEnum path_enum_value = 30;
   282	pathenum.MessagePathEnum.NestedPathEnum nested_path_enum_value = 31;
   283	sfixed32 sfixed32_value = 15;
   284	sfixed64 sfixed64_value = 16;
   285	sint32 sint32_value = 17;
   286	sint64 sint64_value = 18;
   287	repeated string repeated_string_value = 19;
   288	oneof oneof_value {
   289		google.protobuf.Empty oneof_empty = 20;
   290		string oneof_string = 21;
   291	}
   292
   293	map<string, NumericEnum> map_value = 22;
   294	map<string, string> mapped_string_value = 23;
   295	map<string, Nested> mapped_nested_value = 24;
   296
   297	string nonConventionalNameValue = 26;
   298
   299	google.protobuf.Timestamp timestamp_value = 27;
   300
   301	// repeated enum value. it is comma-separated in query
   302	repeated NumericEnum repeated_enum_value = 28;
   303
   304	// repeated numeric enum comment (This comment is overridden by the field annotation)
   305	repeated NumericEnum repeated_enum_annotation = 32 [(grpc.gateway.protoc_gen_swagger.options.openapiv2_field) = {title: "Repeated numeric enum title", description: "Repeated numeric enum description."}];
   306
   307	// numeric enum comment (This comment is overridden by the field annotation)
   308	NumericEnum enum_value_annotation = 33 [(grpc.gateway.protoc_gen_swagger.options.openapiv2_field) = {title: "Numeric enum title", description: "Numeric enum description."}];
   309
   310	// repeated string comment (This comment is overridden by the field annotation)
   311	repeated string repeated_string_annotation = 34 [(grpc.gateway.protoc_gen_swagger.options.openapiv2_field) = {title: "Repeated string title", description: "Repeated string description."}];
   312
   313	// repeated nested object comment (This comment is overridden by the field annotation)
   314	repeated Nested repeated_nested_annotation = 35 [(grpc.gateway.protoc_gen_swagger.options.openapiv2_field) = {title: "Repeated nested object title", description: "Repeated nested object description."}];
   315
   316	// nested object comments (This comment is overridden by the field annotation)
   317	Nested nested_annotation = 36 [(grpc.gateway.protoc_gen_swagger.options.openapiv2_field) = {title: "Nested object title", description: "Nested object description."}];
   318
   319	int64 int64_override_type = 37 [(grpc.gateway.protoc_gen_swagger.options.openapiv2_field) = {type: INTEGER}];
   320}
   321
   322// ABitOfEverythingRepeated is used to validate repeated path parameter functionality
   323message ABitOfEverythingRepeated {
   324	option (grpc.gateway.protoc_gen_swagger.options.openapiv2_schema) = {
   325		example_string: "{\"path_repeated_bool_value\": [true, true, false, true], \"path_repeated_int32_value\": [1, 2, 3]}"
   326	};
   327
   328	// repeated values. they are comma-separated in path
   329	repeated float path_repeated_float_value = 1;
   330	repeated double path_repeated_double_value = 2;
   331	repeated int64 path_repeated_int64_value = 3;
   332	repeated uint64 path_repeated_uint64_value = 4;
   333	repeated int32 path_repeated_int32_value = 5;
   334	repeated fixed64 path_repeated_fixed64_value = 6;
   335	repeated fixed32 path_repeated_fixed32_value = 7;
   336	repeated bool path_repeated_bool_value = 8;
   337	repeated string path_repeated_string_value = 9;
   338	repeated bytes path_repeated_bytes_value = 10;
   339	repeated uint32 path_repeated_uint32_value = 11;
   340	repeated NumericEnum path_repeated_enum_value = 12;
   341	repeated sfixed32 path_repeated_sfixed32_value = 13;
   342	repeated sfixed64 path_repeated_sfixed64_value = 14;
   343	repeated sint32 path_repeated_sint32_value = 15;
   344	repeated sint64 path_repeated_sint64_value = 16;
   345}
   346
   347message Body {
   348	string name = 1;
   349}
   350
   351message MessageWithBody {
   352	string id = 1;
   353	Body data = 2;
   354}
   355
   356
   357// NumericEnum is one or zero.
   358enum NumericEnum {
   359	// ZERO means 0
   360	ZERO = 0;
   361	// ONE means 1
   362	ONE = 1;
   363}
   364
   365// UpdateV2Request request for update includes the message and the update mask
   366message UpdateV2Request {
   367	ABitOfEverything abe = 1;
   368	google.protobuf.FieldMask update_mask = 2;
   369}
   370
   371// An example resource type from AIP-123 used to test the behavior described in
   372// the CreateBookRequest message.
   373//
   374// See: https://google.aip.dev/123
   375message Book {
   376	// The resource name of the book.
   377	//
   378	// Format: `publishers/{publisher}/books/{book}`
   379	//
   380	// Example: `publishers/1257894000000000000/books/my-book`
   381	string name = 1;
   382
   383	// Output only. The book's ID.
   384	string id = 2;
   385
   386	// Output only. Creation time of the book.
   387	google.protobuf.Timestamp create_time = 3;
   388}
   389
   390// A standard Create message from AIP-133 with a user-specified ID.
   391// The user-specified ID (the `book_id` field in this example) must become a
   392// query parameter in the OpenAPI spec.
   393//
   394// See: https://google.aip.dev/133#user-specified-ids
   395message CreateBookRequest {
   396	// The publisher in which to create the book.
   397	//
   398	// Format: `publishers/{publisher}`
   399	//
   400	// Example: `publishers/1257894000000000000`
   401	string parent = 1;
   402
   403	// The book to create.
   404	Book book = 2;
   405
   406	// The ID to use for the book.
   407	//
   408	// This must start with an alphanumeric character.
   409	string book_id = 3;
   410}
   411
   412// ABitOfEverything service is used to validate that APIs with complicated
   413// proto messages and URL templates are still processed correctly.
   414service ABitOfEverythingService {
   415
   416	option (grpc.gateway.protoc_gen_swagger.options.openapiv2_tag) = {
   417		description: "ABitOfEverythingService description -- which should not be used in place of the documentation comment!"
   418		external_docs: {
   419			url: "https://github.com/grpc-ecosystem/grpc-gateway";
   420			description: "Find out more about EchoService";
   421		}
   422	};
   423
   424	// Create a new ABitOfEverything
   425	//
   426	// This API creates a new ABitOfEverything
   427	rpc Create(ABitOfEverything) returns (ABitOfEverything) {
   428		option (google.api.http) = {
   429			post: "/v1/example/a_bit_of_everything/{float_value}/{double_value}/{int64_value}/separator/{uint64_value}/{int32_value}/{fixed64_value}/{fixed32_value}/{bool_value}/{string_value=strprefix/*}/{uint32_value}/{sfixed32_value}/{sfixed64_value}/{sint32_value}/{sint64_value}/{nonConventionalNameValue}/{enum_value}/{path_enum_value}/{nested_path_enum_value}/{enum_value_annotation}"
   430		};
   431	}
   432	rpc CreateBody(ABitOfEverything) returns (ABitOfEverything) {
   433		option (google.api.http) = {
   434			post: "/v1/example/a_bit_of_everything"
   435			body: "*"
   436		};
   437	}
   438	// Create a book.
   439	rpc CreateBook(CreateBookRequest) returns (Book) {
   440		option (google.api.http) = {
   441			post: "/v1/{parent=publishers/*}/books"
   442			body: "book"
   443		};
   444	}
   445	rpc Lookup(sub2.IdMessage) returns (ABitOfEverything) {
   446		option (google.api.http) = {
   447			get: "/v1/example/a_bit_of_everything/{uuid}"
   448		};
   449	}
   450	rpc Update(ABitOfEverything) returns (google.protobuf.Empty) {
   451		option (google.api.http) = {
   452			put: "/v1/example/a_bit_of_everything/{uuid}"
   453			body: "*"
   454		};
   455	}
   456	rpc UpdateV2(UpdateV2Request) returns (google.protobuf.Empty) {
   457		option (google.api.http) = {
   458			put: "/v2/example/a_bit_of_everything/{abe.uuid}"
   459			body: "abe"
   460			additional_bindings: [
   461				{
   462					patch: "/v2/example/a_bit_of_everything/{abe.uuid}"
   463					body: "abe"
   464				},
   465				{
   466					patch: "/v2a/example/a_bit_of_everything/{abe.uuid}"
   467					body: "*"
   468				}
   469			]
   470		};
   471	}
   472
   473	rpc Delete(sub2.IdMessage) returns (google.protobuf.Empty) {
   474		option (google.api.http) = {
   475			delete: "/v1/example/a_bit_of_everything/{uuid}"
   476		};
   477		option (grpc.gateway.protoc_gen_swagger.options.openapiv2_operation) = {
   478			security: {
   479				security_requirement: {
   480					key: "ApiKeyAuth";
   481					value: {}
   482				}
   483				security_requirement: {
   484					key: "OAuth2";
   485					value: {
   486						scope: "read";
   487						scope: "write";
   488					}
   489				}
   490			}
   491			extensions: {
   492				key: "x-irreversible";
   493				value {
   494					bool_value: true;
   495				}
   496			}
   497		};
   498	}
   499	rpc GetQuery(ABitOfEverything) returns (google.protobuf.Empty) {
   500		option (google.api.http) = {
   501			get: "/v1/example/a_bit_of_everything/query/{uuid}"
   502		};
   503		option (grpc.gateway.protoc_gen_swagger.options.openapiv2_operation) = {
   504			deprecated: true // For testing purposes.
   505			external_docs: {
   506				url: "https://github.com/grpc-ecosystem/grpc-gateway";
   507				description: "Find out more about GetQuery";
   508			}
   509			security: {
   510			}
   511		};
   512	}
   513	rpc GetRepeatedQuery(ABitOfEverythingRepeated) returns (ABitOfEverythingRepeated) {
   514		option (google.api.http) = {
   515			get: "/v1/example/a_bit_of_everything_repeated/{path_repeated_float_value}/{path_repeated_double_value}/{path_repeated_int64_value}/{path_repeated_uint64_value}/{path_repeated_int32_value}/{path_repeated_fixed64_value}/{path_repeated_fixed32_value}/{path_repeated_bool_value}/{path_repeated_string_value}/{path_repeated_bytes_value}/{path_repeated_uint32_value}/{path_repeated_enum_value}/{path_repeated_sfixed32_value}/{path_repeated_sfixed64_value}/{path_repeated_sint32_value}/{path_repeated_sint64_value}"
   516		};
   517	}
   518	// Echo allows posting a StringMessage value.
   519	//
   520	// It also exposes multiple bindings.
   521	//
   522	// This makes it useful when validating that the OpenAPI v2 API
   523	// description exposes documentation correctly on all paths
   524	// defined as additional_bindings in the proto.
   525	rpc Echo(grpc.gateway.examples.internal.sub.StringMessage) returns (grpc.gateway.examples.internal.sub.StringMessage) {
   526		option (google.api.http) = {
   527			get: "/v1/example/a_bit_of_everything/echo/{value}"
   528			additional_bindings {
   529				post: "/v2/example/echo"
   530				body: "value"
   531			}
   532			additional_bindings {
   533				get: "/v2/example/echo"
   534			}
   535		};
   536		option (grpc.gateway.protoc_gen_swagger.options.openapiv2_operation) = {
   537			description: "Description Echo";
   538			summary: "Summary: Echo rpc";
   539			tags: "echo rpc";
   540			external_docs: {
   541				url: "https://github.com/grpc-ecosystem/grpc-gateway";
   542				description: "Find out more Echo";
   543			}
   544			responses: {
   545				key: "200"
   546				value: {
   547					examples: {
   548						key: "application/json"
   549						value: '{"value": "the input value"}'
   550					}
   551				}
   552			}
   553			responses: {
   554				key: "503";
   555				value: {
   556					description: "Returned when the resource is temporarily unavailable.";
   557					extensions: {
   558						key: "x-number";
   559						value {
   560							number_value: 100;
   561						}
   562					}
   563				}
   564			}
   565			responses: {
   566				// Overwrites global definition.
   567				key: "404";
   568				value: {
   569					description: "Returned when the resource does not exist.";
   570					schema: {
   571						json_schema: {
   572							type: INTEGER;
   573						}
   574					}
   575				}
   576			}
   577		};
   578	}
   579	rpc DeepPathEcho(ABitOfEverything) returns (ABitOfEverything) {
   580		option (google.api.http) = {
   581			post: "/v1/example/a_bit_of_everything/{single_nested.name}"
   582			body: "*"
   583		};
   584	}
   585	rpc NoBindings(google.protobuf.Duration) returns (google.protobuf.Empty) {}
   586	rpc Timeout(google.protobuf.Empty) returns (google.protobuf.Empty) {
   587		option (google.api.http) = {
   588			get: "/v2/example/timeout",
   589		};
   590	}
   591	rpc ErrorWithDetails(google.protobuf.Empty) returns (google.protobuf.Empty) {
   592		option (google.api.http) = {
   593			get: "/v2/example/errorwithdetails",
   594		};
   595	}
   596	rpc GetMessageWithBody(MessageWithBody) returns (google.protobuf.Empty) {
   597		option (google.api.http) = {
   598			post: "/v2/example/withbody/{id}",
   599			body: "data"
   600		};
   601	}
   602	rpc PostWithEmptyBody(Body) returns (google.protobuf.Empty) {
   603		option (google.api.http) = {
   604			post: "/v2/example/postwithemptybody/{name}",
   605			body: "*"
   606		};
   607	}
   608	rpc CheckGetQueryParams(ABitOfEverything) returns (ABitOfEverything) {
   609		option (google.api.http) = {
   610			get: "/v1/example/a_bit_of_everything/params/get/{single_nested.name}"
   611		};
   612	}
   613	rpc CheckNestedEnumGetQueryParams(ABitOfEverything) returns (ABitOfEverything) {
   614		option (google.api.http) = {
   615			get: "/v1/example/a_bit_of_everything/params/get/nested_enum/{single_nested.ok}"
   616		};
   617	}
   618	rpc CheckPostQueryParams(ABitOfEverything) returns (ABitOfEverything) {
   619		option (google.api.http) = {
   620			post: "/v1/example/a_bit_of_everything/params/post/{string_value}"
   621			body: "single_nested"
   622		};
   623	}
   624	rpc OverwriteResponseContentType(google.protobuf.Empty) returns (google.protobuf.StringValue) {
   625		option (google.api.http) = {
   626			get: "/v2/example/overwriteresponsecontenttype"
   627		};
   628		option (grpc.gateway.protoc_gen_swagger.options.openapiv2_operation) = {
   629			produces: "application/text"
   630		};
   631	}
   632	rpc CheckExternalPathEnum(pathenum.MessageWithPathEnum) returns (google.protobuf.Empty) {
   633		option (google.api.http) = {
   634			get: "/v2/{value}:check"
   635		};
   636	}
   637	rpc CheckExternalNestedPathEnum(pathenum.MessageWithNestedPathEnum) returns (google.protobuf.Empty) {
   638		option (google.api.http) = {
   639			get: "/v2/{value}:check"
   640		};
   641	}
   642}
   643
   644// camelCase and lowercase service names are valid but not recommended (use TitleCase instead)
   645service camelCaseServiceName {
   646	rpc Empty(google.protobuf.Empty) returns (google.protobuf.Empty) {
   647		option (google.api.http) = {
   648			get: "/v2/example/empty",
   649		};
   650	}
   651}
   652service AnotherServiceWithNoBindings {
   653	rpc NoBindings(google.protobuf.Empty) returns (google.protobuf.Empty) {}
   654}

View as plain text