mirror of https://github.com/zhufuyi/sponge
228 lines
8.0 KiB
Protocol Buffer
228 lines
8.0 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/go-dev-frame/sponge/api/serverNameExample/v1;v1";
|
|
|
|
// Default settings for generating *.swagger.json documents. For reference, see: https://bit.ly/4dE5jj7
|
|
option (grpc.gateway.protoc_gen_openapiv2.options.openapiv2_swagger) = {
|
|
host: "localhost:8080"
|
|
base_path: ""
|
|
info: {
|
|
title: "serverNameExample api docs";
|
|
version: "v1.0.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 a new 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 a new userExample";
|
|
description: "Creates a new userExample entity using the provided data in the request body.";
|
|
};
|
|
}
|
|
|
|
// delete a 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 a userExample by id";
|
|
description: "Deletes a existing userExample identified by the given id in the path.";
|
|
//security: {
|
|
// security_requirement: {
|
|
// key: "BearerAuth";
|
|
// value: {}
|
|
// }
|
|
//}
|
|
};
|
|
}
|
|
|
|
// update a 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 a userExample by id";
|
|
description: "Updates the specified userExample with new data provided in the request body. The target is identified by id in the path.";
|
|
//security: {
|
|
// security_requirement: {
|
|
// key: "BearerAuth";
|
|
// value: {}
|
|
// }
|
|
//}
|
|
};
|
|
}
|
|
|
|
// get userExample details 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 details by id";
|
|
description: "Gets detailed information of a userExample specified by the given id in the path.";
|
|
//security: {
|
|
// security_requirement: {
|
|
// key: "BearerAuth";
|
|
// value: {}
|
|
// }
|
|
//}
|
|
};
|
|
}
|
|
|
|
// get a list of userExamples by custom conditions
|
|
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: "get a list of userExamples by custom conditions";
|
|
description: "Returns a paginated list of userExamples filtered by specified query parameters. The request supports pagination (page number, page size) and filtering 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. When the message fields use snake_case naming (e.g., order_id), the generated swagger.json file
|
|
will use camelCase (e.g., orderId) instead of the expected snake_case. This behavior aligns with
|
|
the JSON tag names used by gRPC, but it can cause the Gin framework to fail to correctly bind and
|
|
retrieve parameter values. There are two ways to resolve this issue:
|
|
(1) Explicitly specify the JSON tag name using the json_name option, such as:
|
|
string order_id = 1 [json_name = "order_id"];
|
|
(2) If you want to switch to camelCase naming and update the JSON tag name accordingly, such as:
|
|
string order_id = 1 [json_name = "orderID", (tagger.tags) = "json:\"orderID\""];
|
|
*/
|
|
|
|
|
|
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
|