mirror of
https://github.com/zhufuyi/sponge.git
synced 2025-10-05 08:46:57 +08:00
227 lines
7.5 KiB
Protocol Buffer
227 lines
7.5 KiB
Protocol Buffer
// todo generate the protobuf code here
|
|
// delete the templates code start
|
|
|
|
syntax = "proto3";
|
|
|
|
package api.serverNameExample.v1;
|
|
|
|
import "validate/validate.proto";
|
|
import "api/types/types.proto";
|
|
import "google/api/annotations.proto";
|
|
import "protoc-gen-openapiv2/options/annotations.proto";
|
|
import "tagger/tagger.proto";
|
|
|
|
option go_package = "github.com/zhufuyi/sponge/api/serverNameExample/v1;v1";
|
|
|
|
// Default settings for generating *.swagger.json documents
|
|
// NOTE: because json does not support 64 bits, the int64 and uint64 types under *.swagger.json are automatically converted to string types
|
|
// Reference https://github.com/grpc-ecosystem/grpc-gateway/blob/db7fbefff7c04877cdb32e16d4a248a024428207/examples/internal/proto/examplepb/a_bit_of_everything.proto
|
|
option (grpc.gateway.protoc_gen_openapiv2.options.openapiv2_swagger) = {
|
|
host: "localhost:8080"
|
|
base_path: ""
|
|
info: {
|
|
title: "serverNameExample api docs";
|
|
version: "2.0";
|
|
}
|
|
schemes: HTTP;
|
|
schemes: HTTPS;
|
|
consumes: "application/json";
|
|
produces: "application/json";
|
|
security_definitions: {
|
|
security: {
|
|
key: "BearerAuth";
|
|
value: {
|
|
type: TYPE_API_KEY;
|
|
in: IN_HEADER;
|
|
name: "Authorization";
|
|
description: "Type Bearer your-jwt-token to Value";
|
|
}
|
|
}
|
|
}
|
|
};
|
|
|
|
service userExample {
|
|
// create userExample
|
|
rpc Create(CreateUserExampleRequest) returns (CreateUserExampleReply) {
|
|
option (google.api.http) = {
|
|
post: "/api/v1/userExample"
|
|
body: "*"
|
|
};
|
|
option (grpc.gateway.protoc_gen_openapiv2.options.openapiv2_operation) = {
|
|
summary: "create userExample",
|
|
description: "submit information to create userExample",
|
|
};
|
|
}
|
|
|
|
// delete userExample by id
|
|
rpc DeleteByID(DeleteUserExampleByIDRequest) returns (DeleteUserExampleByIDReply) {
|
|
option (google.api.http) = {
|
|
delete: "/api/v1/userExample/{id}"
|
|
};
|
|
option (grpc.gateway.protoc_gen_openapiv2.options.openapiv2_operation) = {
|
|
summary: "delete userExample",
|
|
description: "delete userExample by id",
|
|
//security: {
|
|
// security_requirement: {
|
|
// key: "BearerAuth";
|
|
// value: {}
|
|
// }
|
|
//}
|
|
};
|
|
}
|
|
|
|
// update userExample by id
|
|
rpc UpdateByID(UpdateUserExampleByIDRequest) returns (UpdateUserExampleByIDReply) {
|
|
option (google.api.http) = {
|
|
put: "/api/v1/userExample/{id}"
|
|
body: "*"
|
|
};
|
|
option (grpc.gateway.protoc_gen_openapiv2.options.openapiv2_operation) = {
|
|
summary: "update userExample",
|
|
description: "update userExample by id",
|
|
//security: {
|
|
// security_requirement: {
|
|
// key: "BearerAuth";
|
|
// value: {}
|
|
// }
|
|
//}
|
|
};
|
|
}
|
|
|
|
// get userExample by id
|
|
rpc GetByID(GetUserExampleByIDRequest) returns (GetUserExampleByIDReply) {
|
|
option (google.api.http) = {
|
|
get: "/api/v1/userExample/{id}"
|
|
};
|
|
option (grpc.gateway.protoc_gen_openapiv2.options.openapiv2_operation) = {
|
|
summary: "get userExample detail",
|
|
description: "get userExample detail by id",
|
|
//security: {
|
|
// security_requirement: {
|
|
// key: "BearerAuth";
|
|
// value: {}
|
|
// }
|
|
//}
|
|
};
|
|
}
|
|
|
|
// list of userExample by query parameters
|
|
rpc List(ListUserExampleRequest) returns (ListUserExampleReply) {
|
|
option (google.api.http) = {
|
|
post: "/api/v1/userExample/list"
|
|
body: "*"
|
|
};
|
|
option (grpc.gateway.protoc_gen_openapiv2.options.openapiv2_operation) = {
|
|
summary: "list of userExamples by query parameters",
|
|
description: "list of userExamples by paging and conditions",
|
|
//security: {
|
|
// security_requirement: {
|
|
// key: "BearerAuth";
|
|
// value: {}
|
|
// }
|
|
//}
|
|
};
|
|
}
|
|
}
|
|
|
|
|
|
/*
|
|
Notes for defining message fields:
|
|
1. Suggest using camel case style naming for message field names, such as firstName, lastName, etc.
|
|
2. If the message field name ending in 'id', it is recommended to use xxxID naming format, such as userID, orderID, etc.
|
|
3. Add validate rules https://github.com/envoyproxy/protoc-gen-validate#constraint-rules, such as:
|
|
uint64 id = 1 [(validate.rules).uint64.gte = 1];
|
|
|
|
If used to generate code that supports the HTTP protocol, notes for defining message fields:
|
|
1. If the route contains the path parameter, such as /api/v1/userExample/{id}, the defined
|
|
message must contain the name of the path parameter and the name should be added
|
|
with a new tag, such as int64 id = 1 [(tagger.tags) = "uri:\"id\""];
|
|
2. If the request url is followed by a query parameter, such as /api/v1/getUserExample?name=Tom,
|
|
a form tag must be added when defining the query parameter in the message, such as:
|
|
string name = 1 [(tagger.tags) = "form:\"name\""].
|
|
3. If the message field name contain underscores(such as 'field_name'), it will cause a problem
|
|
where the JSON field names of the Swagger request parameters are different from those of the
|
|
GRPC JSON tag names. There are two solutions: Solution 1, remove the underline from the
|
|
message field name. Option 2, use the tool 'protoc-go-inject-tag' to modify the JSON tag name,
|
|
such as: string first_name = 1 ; // @gotags: json:"firstName"
|
|
*/
|
|
|
|
|
|
enum GenderType {
|
|
UNKNOWN = 0;
|
|
MALE = 1;
|
|
FEMALE = 2;
|
|
};
|
|
|
|
message CreateUserExampleRequest {
|
|
string name = 1 [(validate.rules).string.min_len = 2]; // name
|
|
string email = 2 [(validate.rules).string.email = true]; // email
|
|
string password = 3 [(validate.rules).string.min_len = 10]; // password
|
|
string phone = 4 [(validate.rules).string = {pattern: "^1[3456789]\\d{9}$"}]; // phone number
|
|
string avatar = 5 [(validate.rules).string.uri = true]; // avatar
|
|
int32 age = 6 [(validate.rules).int32 = {gte:0, lte: 120}]; // age
|
|
GenderType gender = 7 [(validate.rules).enum.defined_only = true]; // gender, 1:Male, 2:Female, other values:unknown
|
|
}
|
|
|
|
message CreateUserExampleReply {
|
|
uint64 id = 1;
|
|
}
|
|
|
|
message DeleteUserExampleByIDRequest {
|
|
uint64 id = 1 [(validate.rules).uint64.gte = 1, (tagger.tags) = "uri:\"id\"" ];
|
|
}
|
|
|
|
message DeleteUserExampleByIDReply {
|
|
|
|
}
|
|
|
|
message UpdateUserExampleByIDRequest {
|
|
uint64 id = 1 [(validate.rules).uint64.gte = 1 , (tagger.tags) = "uri:\"id\"" ];
|
|
string name = 2; // name
|
|
string email = 3; // email
|
|
string password = 4; // password
|
|
string phone = 5; // phone number
|
|
string avatar = 6; // avatar
|
|
int32 age = 7; // age
|
|
GenderType gender = 8; // gender, 1:Male, 2:Female, other values:unknown
|
|
int32 status = 9; // account status
|
|
int64 loginAt = 10; // login timestamp
|
|
}
|
|
|
|
message UpdateUserExampleByIDReply {
|
|
|
|
}
|
|
|
|
message UserExample {
|
|
uint64 id = 1;
|
|
string name = 2; // name
|
|
string email = 3; // email
|
|
string phone = 4; // phone number
|
|
string avatar = 5; // avatar
|
|
int32 age = 6; // age
|
|
GenderType gender = 7; // gender, 1:Male, 2:Female, other values:unknown
|
|
int32 status = 8; // account status
|
|
int64 loginAt = 9; // login timestamp
|
|
string createdAt = 10; // creation time
|
|
string updatedAt = 11; // update time
|
|
}
|
|
|
|
message GetUserExampleByIDRequest {
|
|
uint64 id = 1 [(validate.rules).uint64.gte = 1, (tagger.tags) = "uri:\"id\"" ];
|
|
}
|
|
|
|
message GetUserExampleByIDReply {
|
|
UserExample userExample = 1;
|
|
}
|
|
|
|
message ListUserExampleRequest {
|
|
api.types.Params params = 1 [(validate.rules).message.required = true];
|
|
}
|
|
|
|
message ListUserExampleReply {
|
|
int64 total = 1;
|
|
repeated UserExample userExamples = 2;
|
|
}
|
|
|
|
// delete the templates code end
|