From a2196f975ecdc3c3cd973702caa58a01d6cf1d4c Mon Sep 17 00:00:00 2001 From: ajikamaludin Date: Fri, 15 Jul 2022 11:00:50 +0700 Subject: [PATCH] generate apidocs --- README.md | 22 ++++++- proto/v1/health/health.pb.go | 101 ++++++++++++++++---------------- proto/v1/health/health.pb.gw.go | 2 +- router/http.go | 25 ++++---- swagger/docs.json | 79 +++++++++++++++++++++++++ 5 files changed, 164 insertions(+), 65 deletions(-) create mode 100644 swagger/docs.json diff --git a/README.md b/README.md index ce6a16a..442dced 100644 --- a/README.md +++ b/README.md @@ -46,7 +46,7 @@ ``` - or test via postman , new -> grpc request -> Enter Server Url : localhost:5566 -> Import proto file / Select Method : Status -> Click Invoke -### Implment gRPC-Gateway +### Implement gRPC-Gateway ref https://github.com/grpc-ecosystem/grpc-gateway - implement `import "google/api/annotations.proto";` in proto file - changes line below in all service methods for rest compile to rest @@ -71,4 +71,24 @@ g.Go(func() error { return router.NewHTTPServer(configs, logger) }) - test `curl localhost:8080/api/v1/health/status`, reponse ``` {"success":true,"code":"0000","desc":"SUCCESS"} +``` +- GENERATE API DOCS: +- `mkdir swagger` +- `cd proto` +- `./gen-apidoc.sh` +- register apidoc to http server in `http.go` implement +``` +######### + +if configs.Config.Env != constants.EnvProduction { + CreateSwagger(mux) +} + +########## + +func CreateSwagger(gwmux *http.ServeMux) { + gwmux.HandleFunc("/api/health/docs.json", func(w http.ResponseWriter, r *http.Request) { + http.ServeFile(w, r, "swagger/docs.json") + }) +} ``` \ No newline at end of file diff --git a/proto/v1/health/health.pb.go b/proto/v1/health/health.pb.go index c635630..13b0235 100644 --- a/proto/v1/health/health.pb.go +++ b/proto/v1/health/health.pb.go @@ -2,7 +2,7 @@ // versions: // protoc-gen-go v1.26.0 // protoc v3.21.2 -// source: v1/health/health.proto +// source: health.proto package health @@ -39,7 +39,7 @@ type Response struct { func (x *Response) Reset() { *x = Response{} if protoimpl.UnsafeEnabled { - mi := &file_v1_health_health_proto_msgTypes[0] + mi := &file_health_proto_msgTypes[0] ms := protoimpl.X.MessageStateOf(protoimpl.Pointer(x)) ms.StoreMessageInfo(mi) } @@ -52,7 +52,7 @@ func (x *Response) String() string { func (*Response) ProtoMessage() {} func (x *Response) ProtoReflect() protoreflect.Message { - mi := &file_v1_health_health_proto_msgTypes[0] + mi := &file_health_proto_msgTypes[0] if protoimpl.UnsafeEnabled && x != nil { ms := protoimpl.X.MessageStateOf(protoimpl.Pointer(x)) if ms.LoadMessageInfo() == nil { @@ -65,7 +65,7 @@ func (x *Response) ProtoReflect() protoreflect.Message { // Deprecated: Use Response.ProtoReflect.Descriptor instead. func (*Response) Descriptor() ([]byte, []int) { - return file_v1_health_health_proto_rawDescGZIP(), []int{0} + return file_health_proto_rawDescGZIP(), []int{0} } func (x *Response) GetSuccess() bool { @@ -89,52 +89,51 @@ func (x *Response) GetDesc() string { return "" } -var File_v1_health_health_proto protoreflect.FileDescriptor +var File_health_proto protoreflect.FileDescriptor -var file_v1_health_health_proto_rawDesc = []byte{ - 0x0a, 0x16, 0x76, 0x31, 0x2f, 0x68, 0x65, 0x61, 0x6c, 0x74, 0x68, 0x2f, 0x68, 0x65, 0x61, 0x6c, - 0x74, 0x68, 0x2e, 0x70, 0x72, 0x6f, 0x74, 0x6f, 0x12, 0x14, 0x61, 0x70, 0x69, 0x2e, 0x67, 0x6f, - 0x67, 0x72, 0x70, 0x63, 0x2e, 0x76, 0x31, 0x2e, 0x68, 0x65, 0x61, 0x6c, 0x74, 0x68, 0x1a, 0x1c, - 0x67, 0x6f, 0x6f, 0x67, 0x6c, 0x65, 0x2f, 0x61, 0x70, 0x69, 0x2f, 0x61, 0x6e, 0x6e, 0x6f, 0x74, - 0x61, 0x74, 0x69, 0x6f, 0x6e, 0x73, 0x2e, 0x70, 0x72, 0x6f, 0x74, 0x6f, 0x1a, 0x1b, 0x67, 0x6f, - 0x6f, 0x67, 0x6c, 0x65, 0x2f, 0x70, 0x72, 0x6f, 0x74, 0x6f, 0x62, 0x75, 0x66, 0x2f, 0x65, 0x6d, - 0x70, 0x74, 0x79, 0x2e, 0x70, 0x72, 0x6f, 0x74, 0x6f, 0x22, 0x4c, 0x0a, 0x08, 0x52, 0x65, 0x73, - 0x70, 0x6f, 0x6e, 0x73, 0x65, 0x12, 0x18, 0x0a, 0x07, 0x73, 0x75, 0x63, 0x63, 0x65, 0x73, 0x73, - 0x18, 0x01, 0x20, 0x01, 0x28, 0x08, 0x52, 0x07, 0x73, 0x75, 0x63, 0x63, 0x65, 0x73, 0x73, 0x12, - 0x12, 0x0a, 0x04, 0x63, 0x6f, 0x64, 0x65, 0x18, 0x02, 0x20, 0x01, 0x28, 0x09, 0x52, 0x04, 0x63, - 0x6f, 0x64, 0x65, 0x12, 0x12, 0x0a, 0x04, 0x64, 0x65, 0x73, 0x63, 0x18, 0x03, 0x20, 0x01, 0x28, - 0x09, 0x52, 0x04, 0x64, 0x65, 0x73, 0x63, 0x32, 0x70, 0x0a, 0x0d, 0x48, 0x65, 0x61, 0x6c, 0x74, - 0x68, 0x53, 0x65, 0x72, 0x76, 0x69, 0x63, 0x65, 0x12, 0x5f, 0x0a, 0x06, 0x53, 0x74, 0x61, 0x74, - 0x75, 0x73, 0x12, 0x16, 0x2e, 0x67, 0x6f, 0x6f, 0x67, 0x6c, 0x65, 0x2e, 0x70, 0x72, 0x6f, 0x74, - 0x6f, 0x62, 0x75, 0x66, 0x2e, 0x45, 0x6d, 0x70, 0x74, 0x79, 0x1a, 0x1e, 0x2e, 0x61, 0x70, 0x69, - 0x2e, 0x67, 0x6f, 0x67, 0x72, 0x70, 0x63, 0x2e, 0x76, 0x31, 0x2e, 0x68, 0x65, 0x61, 0x6c, 0x74, - 0x68, 0x2e, 0x52, 0x65, 0x73, 0x70, 0x6f, 0x6e, 0x73, 0x65, 0x22, 0x1d, 0x82, 0xd3, 0xe4, 0x93, - 0x02, 0x17, 0x12, 0x15, 0x2f, 0x61, 0x70, 0x69, 0x2f, 0x76, 0x31, 0x2f, 0x68, 0x65, 0x61, 0x6c, - 0x74, 0x68, 0x2f, 0x73, 0x74, 0x61, 0x74, 0x75, 0x73, 0x42, 0x37, 0x5a, 0x35, 0x67, 0x69, 0x74, - 0x68, 0x75, 0x62, 0x2e, 0x63, 0x6f, 0x6d, 0x2f, 0x61, 0x6a, 0x69, 0x6b, 0x61, 0x6d, 0x61, 0x6c, - 0x75, 0x64, 0x69, 0x6e, 0x2f, 0x67, 0x6f, 0x2d, 0x67, 0x72, 0x70, 0x63, 0x5f, 0x62, 0x61, 0x73, - 0x69, 0x63, 0x2f, 0x70, 0x72, 0x6f, 0x74, 0x6f, 0x2f, 0x76, 0x31, 0x2f, 0x68, 0x65, 0x61, 0x6c, - 0x74, 0x68, 0x62, 0x06, 0x70, 0x72, 0x6f, 0x74, 0x6f, 0x33, +var file_health_proto_rawDesc = []byte{ + 0x0a, 0x0c, 0x68, 0x65, 0x61, 0x6c, 0x74, 0x68, 0x2e, 0x70, 0x72, 0x6f, 0x74, 0x6f, 0x12, 0x14, + 0x61, 0x70, 0x69, 0x2e, 0x67, 0x6f, 0x67, 0x72, 0x70, 0x63, 0x2e, 0x76, 0x31, 0x2e, 0x68, 0x65, + 0x61, 0x6c, 0x74, 0x68, 0x1a, 0x1c, 0x67, 0x6f, 0x6f, 0x67, 0x6c, 0x65, 0x2f, 0x61, 0x70, 0x69, + 0x2f, 0x61, 0x6e, 0x6e, 0x6f, 0x74, 0x61, 0x74, 0x69, 0x6f, 0x6e, 0x73, 0x2e, 0x70, 0x72, 0x6f, + 0x74, 0x6f, 0x1a, 0x1b, 0x67, 0x6f, 0x6f, 0x67, 0x6c, 0x65, 0x2f, 0x70, 0x72, 0x6f, 0x74, 0x6f, + 0x62, 0x75, 0x66, 0x2f, 0x65, 0x6d, 0x70, 0x74, 0x79, 0x2e, 0x70, 0x72, 0x6f, 0x74, 0x6f, 0x22, + 0x4c, 0x0a, 0x08, 0x52, 0x65, 0x73, 0x70, 0x6f, 0x6e, 0x73, 0x65, 0x12, 0x18, 0x0a, 0x07, 0x73, + 0x75, 0x63, 0x63, 0x65, 0x73, 0x73, 0x18, 0x01, 0x20, 0x01, 0x28, 0x08, 0x52, 0x07, 0x73, 0x75, + 0x63, 0x63, 0x65, 0x73, 0x73, 0x12, 0x12, 0x0a, 0x04, 0x63, 0x6f, 0x64, 0x65, 0x18, 0x02, 0x20, + 0x01, 0x28, 0x09, 0x52, 0x04, 0x63, 0x6f, 0x64, 0x65, 0x12, 0x12, 0x0a, 0x04, 0x64, 0x65, 0x73, + 0x63, 0x18, 0x03, 0x20, 0x01, 0x28, 0x09, 0x52, 0x04, 0x64, 0x65, 0x73, 0x63, 0x32, 0x70, 0x0a, + 0x0d, 0x48, 0x65, 0x61, 0x6c, 0x74, 0x68, 0x53, 0x65, 0x72, 0x76, 0x69, 0x63, 0x65, 0x12, 0x5f, + 0x0a, 0x06, 0x53, 0x74, 0x61, 0x74, 0x75, 0x73, 0x12, 0x16, 0x2e, 0x67, 0x6f, 0x6f, 0x67, 0x6c, + 0x65, 0x2e, 0x70, 0x72, 0x6f, 0x74, 0x6f, 0x62, 0x75, 0x66, 0x2e, 0x45, 0x6d, 0x70, 0x74, 0x79, + 0x1a, 0x1e, 0x2e, 0x61, 0x70, 0x69, 0x2e, 0x67, 0x6f, 0x67, 0x72, 0x70, 0x63, 0x2e, 0x76, 0x31, + 0x2e, 0x68, 0x65, 0x61, 0x6c, 0x74, 0x68, 0x2e, 0x52, 0x65, 0x73, 0x70, 0x6f, 0x6e, 0x73, 0x65, + 0x22, 0x1d, 0x82, 0xd3, 0xe4, 0x93, 0x02, 0x17, 0x12, 0x15, 0x2f, 0x61, 0x70, 0x69, 0x2f, 0x76, + 0x31, 0x2f, 0x68, 0x65, 0x61, 0x6c, 0x74, 0x68, 0x2f, 0x73, 0x74, 0x61, 0x74, 0x75, 0x73, 0x42, + 0x37, 0x5a, 0x35, 0x67, 0x69, 0x74, 0x68, 0x75, 0x62, 0x2e, 0x63, 0x6f, 0x6d, 0x2f, 0x61, 0x6a, + 0x69, 0x6b, 0x61, 0x6d, 0x61, 0x6c, 0x75, 0x64, 0x69, 0x6e, 0x2f, 0x67, 0x6f, 0x2d, 0x67, 0x72, + 0x70, 0x63, 0x5f, 0x62, 0x61, 0x73, 0x69, 0x63, 0x2f, 0x70, 0x72, 0x6f, 0x74, 0x6f, 0x2f, 0x76, + 0x31, 0x2f, 0x68, 0x65, 0x61, 0x6c, 0x74, 0x68, 0x62, 0x06, 0x70, 0x72, 0x6f, 0x74, 0x6f, 0x33, } var ( - file_v1_health_health_proto_rawDescOnce sync.Once - file_v1_health_health_proto_rawDescData = file_v1_health_health_proto_rawDesc + file_health_proto_rawDescOnce sync.Once + file_health_proto_rawDescData = file_health_proto_rawDesc ) -func file_v1_health_health_proto_rawDescGZIP() []byte { - file_v1_health_health_proto_rawDescOnce.Do(func() { - file_v1_health_health_proto_rawDescData = protoimpl.X.CompressGZIP(file_v1_health_health_proto_rawDescData) +func file_health_proto_rawDescGZIP() []byte { + file_health_proto_rawDescOnce.Do(func() { + file_health_proto_rawDescData = protoimpl.X.CompressGZIP(file_health_proto_rawDescData) }) - return file_v1_health_health_proto_rawDescData + return file_health_proto_rawDescData } -var file_v1_health_health_proto_msgTypes = make([]protoimpl.MessageInfo, 1) -var file_v1_health_health_proto_goTypes = []interface{}{ +var file_health_proto_msgTypes = make([]protoimpl.MessageInfo, 1) +var file_health_proto_goTypes = []interface{}{ (*Response)(nil), // 0: api.gogrpc.v1.health.Response (*emptypb.Empty)(nil), // 1: google.protobuf.Empty } -var file_v1_health_health_proto_depIdxs = []int32{ +var file_health_proto_depIdxs = []int32{ 1, // 0: api.gogrpc.v1.health.HealthService.Status:input_type -> google.protobuf.Empty 0, // 1: api.gogrpc.v1.health.HealthService.Status:output_type -> api.gogrpc.v1.health.Response 1, // [1:2] is the sub-list for method output_type @@ -144,13 +143,13 @@ var file_v1_health_health_proto_depIdxs = []int32{ 0, // [0:0] is the sub-list for field type_name } -func init() { file_v1_health_health_proto_init() } -func file_v1_health_health_proto_init() { - if File_v1_health_health_proto != nil { +func init() { file_health_proto_init() } +func file_health_proto_init() { + if File_health_proto != nil { return } if !protoimpl.UnsafeEnabled { - file_v1_health_health_proto_msgTypes[0].Exporter = func(v interface{}, i int) interface{} { + file_health_proto_msgTypes[0].Exporter = func(v interface{}, i int) interface{} { switch v := v.(*Response); i { case 0: return &v.state @@ -167,20 +166,20 @@ func file_v1_health_health_proto_init() { out := protoimpl.TypeBuilder{ File: protoimpl.DescBuilder{ GoPackagePath: reflect.TypeOf(x{}).PkgPath(), - RawDescriptor: file_v1_health_health_proto_rawDesc, + RawDescriptor: file_health_proto_rawDesc, NumEnums: 0, NumMessages: 1, NumExtensions: 0, NumServices: 1, }, - GoTypes: file_v1_health_health_proto_goTypes, - DependencyIndexes: file_v1_health_health_proto_depIdxs, - MessageInfos: file_v1_health_health_proto_msgTypes, + GoTypes: file_health_proto_goTypes, + DependencyIndexes: file_health_proto_depIdxs, + MessageInfos: file_health_proto_msgTypes, }.Build() - File_v1_health_health_proto = out.File - file_v1_health_health_proto_rawDesc = nil - file_v1_health_health_proto_goTypes = nil - file_v1_health_health_proto_depIdxs = nil + File_health_proto = out.File + file_health_proto_rawDesc = nil + file_health_proto_goTypes = nil + file_health_proto_depIdxs = nil } // Reference imports to suppress errors if they are not otherwise used. @@ -260,5 +259,5 @@ var _HealthService_serviceDesc = grpc.ServiceDesc{ }, }, Streams: []grpc.StreamDesc{}, - Metadata: "v1/health/health.proto", + Metadata: "health.proto", } diff --git a/proto/v1/health/health.pb.gw.go b/proto/v1/health/health.pb.gw.go index 0c7f161..e1933b9 100644 --- a/proto/v1/health/health.pb.gw.go +++ b/proto/v1/health/health.pb.gw.go @@ -1,5 +1,5 @@ // Code generated by protoc-gen-grpc-gateway. DO NOT EDIT. -// source: v1/health/health.proto +// source: health.proto /* Package health is a reverse proxy. diff --git a/router/http.go b/router/http.go index 2f2e394..b2194fb 100644 --- a/router/http.go +++ b/router/http.go @@ -7,6 +7,7 @@ import ( "net/http" "github.com/ajikamaludin/go-grpc_basic/configs" + "github.com/ajikamaludin/go-grpc_basic/pkg/v1/utils/constants" hlpb "github.com/ajikamaludin/go-grpc_basic/proto/v1/health" "github.com/gorilla/handlers" "github.com/grpc-ecosystem/grpc-gateway/runtime" @@ -44,9 +45,9 @@ func NewHTTPServer(configs *configs.Configs, loggger *logrus.Logger) error { mux := http.NewServeMux() mux.Handle("/", rmux) - // if configs.Config.Env != constants.EnvProduction { - // CreateSwagger(mux) - // } + if configs.Config.Env != constants.EnvProduction { + CreateSwagger(mux) + } headerOk := handlers.AllowedHeaders([]string{"Accept", "Accept-Language", "Content-Language", "Content-Type", "X-Requested-With", "Content-Length", "Accept-Encoding", "X-CSRF-Token", "Authorization", "Timezone-Offset"}) originsOk := handlers.AllowedOrigins([]string{"*"}) @@ -64,13 +65,13 @@ func NewHTTPServer(configs *configs.Configs, loggger *logrus.Logger) error { } // // CreateSwagger creates the swagger server serve mux. -// func CreateSwagger(gwmux *http.ServeMux) { -// // register swagger service server -// gwmux.HandleFunc("/api/health/docs.json", func(w http.ResponseWriter, r *http.Request) { -// http.ServeFile(w, r, "swagger/docs.json") -// }) +func CreateSwagger(gwmux *http.ServeMux) { + // // register swagger service server + gwmux.HandleFunc("/api/health/docs.json", func(w http.ResponseWriter, r *http.Request) { + http.ServeFile(w, r, "swagger/docs.json") + }) -// // load swagger-ui file -// fs := http.FileServer(http.Dir("swagger/swagger-ui")) -// gwmux.Handle("/api/health/docs/", http.StripPrefix("/api/health/docs", fs)) -// } + // // load swagger-ui file + // fs := http.FileServer(http.Dir("swagger/swagger-ui")) + // gwmux.Handle("/api/health/docs/", http.StripPrefix("/api/health/docs", fs)) +} diff --git a/swagger/docs.json b/swagger/docs.json new file mode 100644 index 0000000..13ce532 --- /dev/null +++ b/swagger/docs.json @@ -0,0 +1,79 @@ +{ + "swagger": "2.0", + "consumes": [ + "application/json" + ], + "produces": [ + "application/json" + ], + "paths": { + "/api/v1/health/status": { + "get": { + "operationId": "HealthService_Status", + "responses": { + "200": { + "description": "A successful response.", + "schema": { + "$ref": "#/definitions/healthResponse" + } + }, + "default": { + "description": "An unexpected error response.", + "schema": { + "$ref": "#/definitions/runtimeError" + } + } + } + } + } + }, + "definitions": { + "healthResponse": { + "type": "object", + "properties": { + "success": { + "type": "boolean" + }, + "code": { + "type": "string" + }, + "desc": { + "type": "string" + } + } + }, + "protobufAny": { + "type": "object", + "properties": { + "type_url": { + "type": "string" + }, + "value": { + "type": "string", + "format": "byte" + } + } + }, + "runtimeError": { + "type": "object", + "properties": { + "error": { + "type": "string" + }, + "code": { + "type": "integer", + "format": "int32" + }, + "message": { + "type": "string" + }, + "details": { + "type": "array", + "items": { + "$ref": "#/definitions/protobufAny" + } + } + } + } + } +}