{"id":24105473,"url":"https://github.com/kralicky/ragu","last_synced_at":"2025-05-12T10:16:08.022Z","repository":{"id":40591887,"uuid":"384868170","full_name":"kralicky/ragu","owner":"kralicky","description":"Protobuf code generator without protoc, for Go","archived":false,"fork":false,"pushed_at":"2023-12-06T20:47:24.000Z","size":458,"stargazers_count":6,"open_issues_count":0,"forks_count":1,"subscribers_count":1,"default_branch":"main","last_synced_at":"2025-05-12T10:16:01.408Z","etag":null,"topics":["compiler","go","grpc","protobuf"],"latest_commit_sha":null,"homepage":"","language":"Go","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/kralicky.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2021-07-11T05:33:57.000Z","updated_at":"2023-08-04T15:48:31.000Z","dependencies_parsed_at":"2023-10-03T05:43:41.214Z","dependency_job_id":"0bb61850-6007-449b-bf90-dd59b6459e33","html_url":"https://github.com/kralicky/ragu","commit_stats":null,"previous_names":[],"tags_count":24,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/kralicky%2Fragu","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/kralicky%2Fragu/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/kralicky%2Fragu/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/kralicky%2Fragu/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/kralicky","download_url":"https://codeload.github.com/kralicky/ragu/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":253717612,"owners_count":21952517,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["compiler","go","grpc","protobuf"],"created_at":"2025-01-10T20:53:15.578Z","updated_at":"2025-05-12T10:16:07.956Z","avatar_url":"https://github.com/kralicky.png","language":"Go","funding_links":[],"categories":[],"sub_categories":[],"readme":"# ragù 🍝\n\nragù is a pure-go protobuf code generator library.\n\n## Features\n\n- Doesn't require protoc, other binaries, or cgo; it is completely self-contained.\n- Can generate GRPC bindings, GRPC Gateway bindings, and Swagger definitions.\n- Can generate Python bindings equivalent to python-betterproto\n- Import proto files from project dependencies using go module paths (with gogoproto and Kubernetes compatibility!)\n\n## How to use\n\nRagu is designed to be used as a Go library, as part of your build process. I recommend using [mage](https://github.com/magefile/mage) or a similar tool.\n\n1. Import ragu: `go get github.com/kralicky/ragu@latest`\n2. Generate code by calling `ragu.GenerateCode()`:\n\n```go\nfiles, err := ragu.GenerateCode(ragu.DefaultGenerators(), \"**/*.proto\")\nif err != nil {\n  return err\n}\nfor _, f := range files {\n  if err := file.WriteToDisk(); err != nil {\n    return err\n  }\n}\n```\n\n## `go_package` and imports\n\nThe `go_package` file option is used to determine the import path of your protobuf definitions, as well as the default path of generated files.\nIt should be set to the full import path of the package where the generated code will be placed, similar to how Go modules work.\n\nFor example, given the following files:\n\n```\npkg/\n  foo/\n    foo.proto\n  bar/\n    bar.proto\n```\n\n```protobuf\n// pkg/foo/foo.proto\nsyntax = \"proto3\";\noption go_package = \"github.com/username/project/pkg/foo\";\n\npackage foo;\n\nmessage Foo {\n  string str = 1;\n}\n```\n\n```protobuf\n// pkg/bar/bar.proto\nsyntax = \"proto3\";\noption go_package = \"github.com/username/project/pkg/bar\";\n\nimport \"github.com/username/project/pkg/foo/foo.proto\"; // ragu-style import path\nimport \"google/protobuf/empty.proto\"                    // standard import path\n\npackage bar;\n\nservice Bar {\n  rpc Test(foo.Foo) returns (google.protobuf.Empty);\n}\n```\n\n`ragu.GenerateCode()` will generate the following new files:\n\n```diff\npkg/\n  foo/\n    foo.proto\n+   foo.pb.go\n  bar/\n    bar.proto\n+   bar.pb.go\n+   bar_grpc.pb.go\n```\n\n## GRPC Gateway\n\ngrpc-gateway is supported by default, and will generate code if the `google.api.http` option is set on a service method.\n\n```protobuf\n// pkg/baz/baz.proto\nsyntax = \"proto3\";\noption go_package = \"github.com/username/project/pkg/baz\";\n\nimport \"google/api/annotations.proto\";\nimport \"github.com/username/project/pkg/foo/foo.proto\";\n\npackage baz;\n\nservice Baz {\n  rpc Test(foo.Foo) returns (google.protobuf.Empty) {\n    option (google.api.http) = {\n      post: \"/test\"\n      body: \"*\"\n    };\n  }\n}\n```\n\n`ragu.GenerateCode()` will generate the following new files:\n\n```diff\npkg/\n  foo/\n    foo.proto\n    foo.pb.go\n  bar/\n    bar.proto\n    bar.pb.go\n    bar_grpc.pb.go\n  baz/\n    baz.proto\n+   baz.pb.go\n+   baz_grpc.pb.go\n+   baz.pb.gw.go\n```\n\n### Swagger definitions\n\nSwagger definitions are generated only if the openapiv2_swagger file option is set when using grpc-gateway.\n\n```protobuf\n// pkg/baz/baz.proto\nsyntax = \"proto3\";\noption go_package = \"github.com/username/project/pkg/baz\";\n\nimport \"google/api/annotations.proto\";\nimport \"github.com/username/project/pkg/foo/foo.proto\";\nimport \"github.com/kralicky/grpc-gateway/v2/protoc-gen-openapiv2/options/annotations.proto\";\n\npackage baz;\n\noption (grpc.gateway.protoc_gen_openapiv2.options.openapiv2_swagger) = {\n  info: {\n    title: \"Baz\";\n    version: \"1.0\";\n    license: {\n      name: \"Apache 2.0\";\n      url: \"https://github.com/rancher/opni/blob/main/LICENSE\";\n    };\n  };\n};\n\nservice Baz {\n  rpc Test(foo.Foo) returns (google.protobuf.Empty) {\n    option (google.api.http) = {\n      post: \"/test\"\n      body: \"*\"\n    };\n  }\n}\n```\n\n`ragu.GenerateCode()` will generate the following new files:\n\n```diff\npkg/\n  foo/\n    foo.proto\n    foo.pb.go\n  bar/\n    bar.proto\n    bar.pb.go\n    bar_grpc.pb.go\n  baz/\n    baz.proto\n    baz.pb.go\n    baz_grpc.pb.go\n    baz.pb.gw.go\n+   baz.swagger.json\n```\n\n## gogoproto compatibility\n\nYou can import gogoproto-generated protobuf definitions as follows:\n\n```protobuf\nimport \"github.com/cockroachdb/errors/errorspb/errors.proto\";\nimport \"k8s.io/api/core/v1/generated.proto\";\n\nmessage Foo {\n  k8s.io.api.core.v1.Pod pod = 1;\n  cockroach.errorspb.EncodedError err = 2;\n}\n```\n### Notes:\n- Any imported packages must exist in your `go.mod` file.\n- If the imported protobuf code imports `gogoproto/gogo.proto`, you must import `github.com/kralicky/ragu/compat` where `ragu.GenerateCode()` is called.\n- If you need to use the file descriptors from imported gogoproto definitions at runtime, call `compat.LoadGogoFileDescriptor()` to add the descriptor to `protoregistry.GlobalFiles`.\n\n```go\nimport \"github.com/kralicky/ragu/compat\"\nfunc init() {\n\tcompat.LoadGogoFileDescriptor(\"k8s.io/api/core/v1/generated.proto\")\n}\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fkralicky%2Fragu","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fkralicky%2Fragu","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fkralicky%2Fragu/lists"}