{"id":37148989,"url":"https://github.com/merzzzl/proto-rest-api","last_synced_at":"2026-01-14T17:35:51.194Z","repository":{"id":234137157,"uuid":"782567297","full_name":"merzzzl/proto-rest-api","owner":"merzzzl","description":"A tool for automatic generation of RESTful APIs based on Protocol Buffers (Protobuf) definitions. The project uses the protoc-gen-go-rest plugin to create OpenAPI specifications and other API artifacts.","archived":false,"fork":false,"pushed_at":"2025-09-27T16:57:58.000Z","size":1702,"stargazers_count":1,"open_issues_count":0,"forks_count":0,"subscribers_count":2,"default_branch":"main","last_synced_at":"2025-09-27T18:31:13.370Z","etag":null,"topics":["go","openapi","protoc","rest"],"latest_commit_sha":null,"homepage":"","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/merzzzl.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,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2024-04-05T14:59:37.000Z","updated_at":"2025-09-27T16:57:38.000Z","dependencies_parsed_at":"2025-10-03T15:18:01.337Z","dependency_job_id":null,"html_url":"https://github.com/merzzzl/proto-rest-api","commit_stats":null,"previous_names":["merzzzl/proto-rest-api"],"tags_count":29,"template":false,"template_full_name":null,"purl":"pkg:github/merzzzl/proto-rest-api","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/merzzzl%2Fproto-rest-api","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/merzzzl%2Fproto-rest-api/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/merzzzl%2Fproto-rest-api/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/merzzzl%2Fproto-rest-api/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/merzzzl","download_url":"https://codeload.github.com/merzzzl/proto-rest-api/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/merzzzl%2Fproto-rest-api/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":28428730,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-01-14T16:38:47.836Z","status":"ssl_error","status_checked_at":"2026-01-14T16:34:59.695Z","response_time":107,"last_error":"SSL_connect returned=1 errno=0 peeraddr=140.82.121.5:443 state=error: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"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":["go","openapi","protoc","rest"],"created_at":"2026-01-14T17:35:50.640Z","updated_at":"2026-01-14T17:35:51.185Z","avatar_url":"https://github.com/merzzzl.png","language":"Go","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Proto REST API Generator\n\nA tool for automatic generation of RESTful APIs based on Protocol Buffers (Protobuf) definitions. The project uses the `protoc-gen-go-rest` plugin to create OpenAPI specifications and other API artifacts.\n\n## Table of Contents\n- [Features](#features)\n- [Prerequisites](#prerequisites)\n- [Quick Start](#quick-start)\n- [Installation](#installation)\n- [Usage](#usage)\n- [REST API Annotations](#rest-api-annotations)\n- [Examples](#examples)\n  - [Basic Example](#basic-example)\n  - [Advanced Features](#advanced-features)\n- [Make Commands](#make-commands)\n- [Streaming API Support](#streaming-api-support)\n- [Authentication](#authentication)\n- [Contributing](#contributing)\n- [License](#license)\n\n## Features\n\n- **OpenAPI 3.0 Specification Generation**: Automatically creates OpenAPI documentation based on Protobuf service definitions.\n- **Flexible Request and Response Handling**: Maps Protobuf messages to REST request bodies, query parameters, and path parameters.\n- **Streaming API Support**: Ability to create streaming APIs with WebSocket support.\n- **Customizable HTTP Methods**: Support for GET, POST, PUT, PATCH, and DELETE.\n- **Built-in Authentication**: Support for Bearer tokens and customizable access scopes.\n- **Customizable HTTP Status Codes**: Ability to specify successful response codes.\n\n## Prerequisites\n\n- Go 1.23 or later\n- Protocol Buffers Compiler (`protoc`) version 3.15 or later\n- Installed `protoc-gen-go` and `protoc-gen-go-rest` plugins\n\n## Quick Start\n\n1. Install the necessary dependencies:\n   ```bash\n   sudo apt install -y protobuf-compiler\n   go install google.golang.org/protobuf/cmd/protoc-gen-go@latest\n   go install github.com/merzzzl/proto-rest-api/cmd/protoc-gen-go-rest@latest\n   export PATH=$PATH:$(go env GOPATH)/bin\n   ```\n\n2. Create a simple proto file:\n   ```proto\n   syntax = \"proto3\";\n   package example;\n   \n   import \"restapi/annotations.proto\";\n   \n   option go_package = \"./api;api\";\n   \n   service ExampleService {\n     option (restapi.service) = {\n       base_path : \"/api/v1\"\n     };\n   \n     rpc Echo(EchoRequest) returns (EchoResponse) {\n       option (restapi.method) = {\n         method : \"GET\"\n         path : \"/echo/:message\"\n         response : \"*\"\n       };\n     }\n   }\n   \n   message EchoRequest {\n     string message = 1;\n   }\n   \n   message EchoResponse {\n     string message = 1;\n   }\n   ```\n\n3. Generate the REST API:\n   ```bash\n   protoc --go_out=. --go-rest_out=. --proto_path=. example.proto\n   ```\n\n4. Run the generated server and explore the REST API.\n\n## Installation\n\n1. Install the Protobuf compiler:\n   ```bash\n   sudo apt install -y protobuf-compiler\n   ```\n\n2. Install the required Go plugins:\n   ```bash\n   go install google.golang.org/protobuf/cmd/protoc-gen-go@latest\n   go install github.com/merzzzl/proto-rest-api/cmd/protoc-gen-go-rest@latest\n   ```\n\n3. Ensure the plugins are in your `PATH`:\n   ```bash\n   export PATH=$PATH:$(go env GOPATH)/bin\n   ```\n\n## Usage\n\n1. Define your Protobuf services and messages in `.proto` files using annotations from the `restapi` package.\n\n2. Generate the REST API and OpenAPI specification:\n   ```bash\n   protoc --go_out=. --go-rest_out=. --proto_path=./path/to/protos your_service.proto\n   ```\n\n3. The generated OpenAPI specification can be found in the output directory.\n\n## REST API Annotations\n\nThe project uses special annotations to describe the REST API:\n\n- `restapi.service` - settings for the entire service:\n  - `base_path` - base path for all service endpoints\n  - `auth` - authentication type (NONE, BEARER)\n  - `auth_scope` - authentication scope\n\n- `restapi.method` - settings for individual methods:\n  - `method` - HTTP method (GET, POST, PUT, PATCH, DELETE)\n  - `path` - path pattern, can contain parameters with `:` prefix and query parameters\n  - `request` - request field for mapping HTTP request body\n  - `response` - response field for mapping HTTP response body\n  - `success_code` - successful HTTP response code (default 200)\n\n## Examples\n\n### Basic Example\n\n```proto\nsyntax = \"proto3\";\npackage example;\n\nimport \"restapi/annotations.proto\";\n\nservice ExampleService {\n  option (restapi.service) = {\n    base_path : \"/api/v1\"\n  };\n\n  rpc Echo(EchoRequest) returns (EchoResponse) {\n    option (restapi.method) = {\n      method : \"GET\"\n      path : \"/echo/:message\"\n      response : \"*\"\n    };\n  }\n}\n\nmessage EchoRequest {\n  string message = 1;\n}\n\nmessage EchoResponse {\n  string message = 1;\n}\n```\n\nGenerate the REST API:\n```bash\nprotoc --go_out=. --go-rest_out=. --proto_path=./protos example.proto\n```\n\n### Advanced Features\n\nThe project supports various REST API usage scenarios, as shown in the `example/proto/example.proto` example:\n\n- Path and query parameters (e.g., `/messages/:id?:page\u0026:per_page`)\n- POST, PUT, PATCH requests with body\n- Streaming APIs with WebSocket support\n- Authentication via Bearer tokens\n\n## Make Commands\n\nThe project includes a Makefile with useful commands:\n\n- `make build` - build the project, generate proto files and install the plugin\n- `make test-runtime` - run tests and generate code coverage report\n- `make example-run` - run the API example\n- `make proto` - generate code from annotation files\n- `make proto-example` - generate code from examples\n- `make lint` - run linter and format code\n\n## Streaming API Support\n\nThe project supports streaming APIs via WebSocket for gRPC methods with the `stream` keyword.\nExample from `example/proto/example.proto`:\n\n```proto\nrpc Echo(stream EchoRequest) returns (stream EchoResponse) {\n  option (restapi.method) = {\n    method : \"GET\"\n    path : \"/echo/:channel\"\n    request : \"*\"\n    response : \"*\"\n  };\n}\n\nrpc Ticker(TickerRequest) returns (stream TickerResponse) {\n  option (restapi.method) = {\n    method : \"GET\"\n    path : \"/ticker/:count\"\n    request : \"*\"\n    response : \"*\"\n  };\n}\n```\n\n## Authentication\n\nThe project supports authentication via Bearer tokens:\n\n```proto\nservice ExampleService {\n  option (restapi.service) = {\n    base_path : \"/api/v1/example\"\n    auth : AUTH_TYPE_BEARER\n    auth_scope : \"JWT\"\n  };\n  \n  // API methods...\n}\n```\n\n## Contributing\n\nContributions to the project are welcome! Please create issues or submit pull requests with improvements or bug fixes.\n\n## License\n\nThis project is licensed under the MIT License. See the [LICENSE](LICENSE) file for details.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmerzzzl%2Fproto-rest-api","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fmerzzzl%2Fproto-rest-api","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmerzzzl%2Fproto-rest-api/lists"}