{"id":13740738,"url":"https://github.com/izumin5210/grapi","last_synced_at":"2025-04-05T01:06:00.267Z","repository":{"id":47533630,"uuid":"122707122","full_name":"izumin5210/grapi","owner":"izumin5210","description":"😮 A surprisingly easy API server and generator in gRPC and Go","archived":false,"fork":false,"pushed_at":"2021-10-25T21:40:25.000Z","size":1006,"stargazers_count":426,"open_issues_count":36,"forks_count":38,"subscribers_count":8,"default_branch":"master","last_synced_at":"2025-03-29T00:07:26.251Z","etag":null,"topics":["api","golang","grpc","microservice"],"latest_commit_sha":null,"homepage":"https://godoc.org/github.com/izumin5210/grapi/pkg/grapiserver","language":"Go","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/izumin5210.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}},"created_at":"2018-02-24T05:42:10.000Z","updated_at":"2025-03-04T10:16:28.000Z","dependencies_parsed_at":"2022-09-05T02:41:39.346Z","dependency_job_id":null,"html_url":"https://github.com/izumin5210/grapi","commit_stats":null,"previous_names":[],"tags_count":16,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/izumin5210%2Fgrapi","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/izumin5210%2Fgrapi/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/izumin5210%2Fgrapi/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/izumin5210%2Fgrapi/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/izumin5210","download_url":"https://codeload.github.com/izumin5210/grapi/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":247271528,"owners_count":20911587,"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":["api","golang","grpc","microservice"],"created_at":"2024-08-03T04:00:51.760Z","updated_at":"2025-04-05T01:06:00.245Z","avatar_url":"https://github.com/izumin5210.png","language":"Go","funding_links":[],"categories":["Language-Specific","grpc"],"sub_categories":["Go"],"readme":"# ![grapi](./grapi.png)\n[![CI](https://github.com/izumin5210/grapi/workflows/CI/badge.svg)](https://github.com/izumin5210/grapi/actions?workflow=CI)\n[![GoDoc](https://godoc.org/github.com/izumin5210/grapi/pkg/grapiserver?status.svg)](https://godoc.org/github.com/izumin5210/grapi/pkg/grapiserver)\n[![Go Report Card](https://goreportcard.com/badge/github.com/izumin5210/grapi)](https://goreportcard.com/report/github.com/izumin5210/grapi)\n[![GitHub release (latest SemVer)](https://img.shields.io/github/v/release/izumin5210/grapi)](http://github.com/izumin5210/grapi/releases/latest)\n[![license](https://img.shields.io/github/license/izumin5210/grapi.svg)](./LICENSE)\n\n:open_mouth: A surprisingly easy API server and generator in gRPC and Go\n\n## Features\n- You can develop and deploy API servers blazingly fast :zap:\n- Easy code generator\n\t- application  (inspired by `rails new` and `create-react-app`)\n\t- gRPC services and their implementations (inspired by `rails g (scaffold_)controller`)\n- User-friendly `protoc` wrapper (inspired by [protoeasy](https://github.com/peter-edge/protoeasy-go))\n- Provides gRPC and HTTP JSON API  with single implementation by using [grpc-gateway](https://github.com/grpc-ecosystem/grpc-gateway)\n- Generates codes based on [google's API design guideline](https://cloud.google.com/apis/design/)\n\n[![asciicast](https://asciinema.org/a/176280.png)](https://asciinema.org/a/176280)\n\n## :warning: Migrate 0.4.x -\u003e 0.5.x :warning:\n[grapiserver](https://godoc.org/github.com/izumin5210/grapi/pkg/grapiserver) will not handle os signals from v0.5.x.\nWe recommend to use [`appctx.Global()`](https://godoc.org/github.com/srvc/appctx#Global) if you want to handle them.\n\n\u003cdetails\u003e\n\u003csummary\u003e:memo: How to migrate\u003c/summary\u003e\n\n0. Bump grapi version\n    - `go get -u github.com/izumin5210/grapi@v0.5'\n1. Update `cmd/server/run.go`\n    - ```diff\n       \t// Application context\n      -\tctx := context.Background()\n      +\tctx := appctx.Global()\n      ```\n    - ```diff\n      -\treturn s.ServeContext(ctx)\n      +\treturn s.Serve(ctx)\n      ```\n\n\u003c/details\u003e\n\n\n## :warning: Migrate 0.3.x -\u003e 0.4.x :warning:\nSome tools that are depended by grapi are updated. If you have a grapi project \u003c=v0.3.x, you should migrate it.\n\n\u003cdetails\u003e\n\u003csummary\u003e:memo: How to migrate\u003c/summary\u003e\n\n0. Bump grapi version\n    - If you use [dep](https://golang.github.io/dep/), update `Gopkg.toml`\n      ```diff\n       [[constraint]]\n         name = \"github.com/izumin5210/grapi\"\n      -  version = \"0.3.0\"\n      +  version = \"0.4.0\"\n      ```\n    - and run `dep ensure`\n1. Update [gex](https://github.com/izumin5210/gex) and `tools.go`\n    - ```\n      go get -u github.com/izumin5210/gex/cmd/gex\n      gex --regen\n      ```\n1. Initialize [Go Modules](https://github.com/golang/go/wiki/Modules)\n    - ```\n      go mod init\n      go mod tidy\n      ```\n1. Update `grapi.toml`\n    - ```diff\n      package = \"yourcompany.yourappname\"\n      \n      [grapi]\n      server_dir = \"./app/server\"\n   \n      [protoc]\n      protos_dir = \"./api/protos\"\n      out_dir = \"./api\"\n      import_dirs = [\n        \"./api/protos\",\n      -  \"./vendor/github.com/grpc-ecosystem/grpc-gateway\",\n      -  \"./vendor/github.com/grpc-ecosystem/grpc-gateway/third_party/googleapis\",\n      +  '{{ module \"github.com/grpc-ecosystem/grpc-gateway\" }}',\n      +  '{{ module \"github.com/grpc-ecosystem/grpc-gateway\" }}/third_party/googleapis',\n      ]\n   \n        [[protoc.plugins]]\n        name = \"go\"\n        args = { plugins = \"grpc\", paths = \"source_relative\" }\n   \n        [[protoc.plugins]]\n        name = \"grpc-gateway\"\n        args = { logtostderr = true, paths = \"source_relative\" }\n   \n        [[protoc.plugins]]\n        name = \"swagger\"\n        args = { logtostderr = true }\n      ```\n1. Drop dep\n    - ```\n      rm Gopkg.*\n      ```\n\n\t\n\u003c/details\u003e\n\n## :warning: Migrate 0.2.x -\u003e 0.3.x :warning:\ngrapi v0.3.0 has some breaking changes. If you have a grapi project \u003c=v0.2.x, you should migrate it.\n\n\u003cdetails\u003e\n\u003csummary\u003e:memo: How to migrate\u003c/summary\u003e\n\n0. Bump grapi version\n    - If you use [dep](https://golang.github.io/dep/), update `Gopkg.toml`\n      ```diff\n       [[constraint]]\n         name = \"github.com/izumin5210/grapi\"\n      -  version = \"0.2.2\"\n      +  version = \"0.3.0\"\n      ```\n    - and run `dep ensure`\n1. Introduce [gex](https://github.com/izumin5210/gex)\n    - ```\n      go get github.com/izumin5210/gex/cmd/gex\n      ```\n1. Add defualt generator plugins:\n    - ```\n      gex \\\n        --add github.com/izumin5210/grapi/cmd/grapi \\\n        --add github.com/izumin5210/grapi/cmd/grapi-gen-command \\\n        --add github.com/izumin5210/grapi/cmd/grapi-gen-service \\\n        --add github.com/izumin5210/grapi/cmd/grapi-gen-scaffold-service \\\n        --add github.com/izumin5210/grapi/cmd/grapi-gen-type\n      ```\n1. Add protoc plugins via gex\n    - ```\n      gex \\\n        --add github.com/golang/protobuf/protoc-gen-go \\\n        --add github.com/grpc-ecosystem/grpc-gateway/protoc-gen-grpc-gateway \\\n        --add github.com/grpc-ecosystem/grpc-gateway/protoc-gen-swagger\n      ```\n    - Remove protoc plugins from `Gopkg.toml`\n      ```diff\n      -required = [\n      -  \"github.com/golang/protobuf/protoc-gen-go\",\n      -  \"github.com/grpc-ecosystem/grpc-gateway/protoc-gen-grpc-gateway\",\n      -  \"github.com/grpc-ecosystem/grpc-gateway/protoc-gen-swagger\",\n      -]\n      ```\n1. Update `grapi.toml`\n    - ```diff\n      +package = \"yourcompany.yourappname\"\n      +\n       [grapi]\n       server_dir = \"./app/server\"\n\n       [protoc]\n       protos_dir = \"./api/protos\"\n       out_dir = \"./api\"\n       import_dirs = [\n      +  \"./api/protos\",\n         \"./vendor/github.com/grpc-ecosystem/grpc-gateway\",\n         \"./vendor/github.com/grpc-ecosystem/grpc-gateway/third_party/googleapis\",\n       ]\n\n         [[protoc.plugins]]\n      -  path = \"./vendor/github.com/golang/protobuf/protoc-gen-go\"\n         name = \"go\"\n         args = { plugins = \"grpc\", paths = \"source_relative\" }\n\n         [[protoc.plugins]]\n      -  path = \"./vendor/github.com/grpc-ecosystem/grpc-gateway/protoc-gen-grpc-gateway\"\n         name = \"grpc-gateway\"\n      -  args = { logtostderr = true }\n      +  args = { logtostderr = true, paths = \"source_relative\" }\n\n         [[protoc.plugins]]\n      -  path = \"./vendor/github.com/grpc-ecosystem/grpc-gateway/protoc-gen-swagger\"\n         name = \"swagger\"\n         args = { logtostderr = true }\n      ```\n\n\u003c/details\u003e\n\n\n## Getting Started\n\n### Create a new application\n```\n$ grapi init awesome-app\n```\n\n### Create a new service\n```\n$ grapi g service books\n```\n\nOr, if you need full [standard methods](https://cloud.google.com/apis/design/standard_methods), you can get them with following command:\n\n```\n$ grapi g scaffold-service books\n```\n\nAnd you should register generated services to the `grapiserver.Engine` instance:\n\n```diff\n // app/run.go\n \n // Run starts the grapiserver.\n func Run() error {\n \ts := grapiserver.New(\n \t\tgrapiserver.WithDefaultLogger(),\n \t\tgrapiserver.WithServers(\n+\t\t\tserver.NewBookServiceServer(),\n-\t\t// TODO\n \t\t),\n \t)\n \treturn s.Serve()\n }\n```\n\nIf you updated service definition, you can re-generate `.pb.go` and `.pb.gw.go` with following command:\n\n```\n$ grapi protoc\n```\n\n### Start server\n\n```\n$ grapi server\n```\n\n### User-defined commands\n\n```\n$ grapi g command import-books\n$ vim cmd/import-books/run.go  # implements the command\n$ grapi import-books  # run the command\n```\n\n### Build commands (including server)\n\n```\n$ grapi build\n```\n\n## Installation\n\n1. **grapi**\n    - Linux\n        - `curl -Lo grapi https://github.com/izumin5210/grapi/releases/download/v0.2.2/grapi_linux_amd64 \u0026\u0026 chmod +x grapi \u0026\u0026 sudo mv grapi /usr/local/bin`\n    - macOS\n        - `brew install izumin5210/tools/grapi`\n    - others\n        - `go get github.com/izumin5210/grapi/cmd/grapi`\n1. **dep** or **Modules**\n    - [dep](https://golang.github.io/dep/)\n        - macOS\n            - `brew install dep`\n        - others\n            - See [Installation · dep](https://golang.github.io/dep/docs/installation.html)\n            - `curl https://raw.githubusercontent.com/golang/dep/master/install.sh | sh`\n    - [Modules](https://github.com/golang/go/wiki/Modules) (experimental)\n        - Use Go 1.11 and set `GO111MODULE=on` your env vars\n1. **protoc**\n    - macOS\n        - `brew install protobuf`\n    - others\n        - Download and install from [google/protobuf](https://github.com/google/protobuf)\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fizumin5210%2Fgrapi","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fizumin5210%2Fgrapi","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fizumin5210%2Fgrapi/lists"}