{"id":13596241,"url":"https://github.com/grpc-swagger/grpc-swagger","last_synced_at":"2025-04-05T11:12:31.720Z","repository":{"id":38175819,"uuid":"163566292","full_name":"grpc-swagger/grpc-swagger","owner":"grpc-swagger","description":"Debugging gRPC application with swagger-ui.","archived":false,"fork":false,"pushed_at":"2023-06-30T18:45:57.000Z","size":1729,"stargazers_count":433,"open_issues_count":14,"forks_count":59,"subscribers_count":9,"default_branch":"master","last_synced_at":"2025-03-29T10:09:53.538Z","etag":null,"topics":["grpc","grpc-api","grpc-ecosystem","grpc-json","grpc-swagger","openapi","swagger"],"latest_commit_sha":null,"homepage":"","language":"Java","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/grpc-swagger.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":"CODE_OF_CONDUCT.md","threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null}},"created_at":"2018-12-30T06:14:45.000Z","updated_at":"2025-03-27T05:03:14.000Z","dependencies_parsed_at":"2024-01-07T18:07:09.400Z","dependency_job_id":null,"html_url":"https://github.com/grpc-swagger/grpc-swagger","commit_stats":null,"previous_names":[],"tags_count":9,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/grpc-swagger%2Fgrpc-swagger","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/grpc-swagger%2Fgrpc-swagger/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/grpc-swagger%2Fgrpc-swagger/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/grpc-swagger%2Fgrpc-swagger/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/grpc-swagger","download_url":"https://codeload.github.com/grpc-swagger/grpc-swagger/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":247325694,"owners_count":20920714,"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":["grpc","grpc-api","grpc-ecosystem","grpc-json","grpc-swagger","openapi","swagger"],"created_at":"2024-08-01T16:02:13.102Z","updated_at":"2025-04-05T11:12:31.686Z","avatar_url":"https://github.com/grpc-swagger.png","language":"Java","funding_links":[],"categories":["Java","Tools"],"sub_categories":["Testing"],"readme":"# gRPC-swagger\n\n[![Build Status](https://travis-ci.com/grpc-swagger/grpc-swagger.svg?branch=master)](https://travis-ci.com/grpc-swagger/grpc-swagger)\n[![Coverage Status](https://codecov.io/gh/grpc-swagger/grpc-swagger/branch/master/graph/badge.svg)](https://codecov.io/gh/grpc-swagger/grpc-swagger)\n[![GitHub license](https://img.shields.io/github/license/Naereen/StrapDown.js.svg)](https://github.com/Naereen/StrapDown.js/blob/master/LICENSE)\n\n[中文文档](README_CN.md)\n\n\u003c!-- toc --\u003e\n\n- [What is gRPC-swagger](#what-is-grpc-swagger)\n- [Feature List](#feature-list)\n- [Screenshots](#screenshots)\n- [Live Demo](#live-demo)\n- [Build and Run](#build-and-run)\n  * [Use released jar](#use-released-jar)\n  * [Build from source](#build-from-source)\n  * [Other parameters](#other-parameters)\n- [How to use it](#how-to-use-it)\n- [API](#api)\n  * [Register Endpoint](#register-endpoint)\n  * [Services List](#services-list)\n  * [Call gRPC Method](#call-grpc-method)\n  * [Swagger API](#swagger-api)\n- [Acknowledgment](#acknowledgment)\n- [Contribute](#contribute)\n- [FAQ](#faq)\n- [License](#license)\n\n\u003c!-- tocstop --\u003e\n\n## What is gRPC-swagger\n\ngRPC-swagger is a [gRPC](https://github.com/grpc/) debuggling tool developed based on [gRPC reflection](https://github.com/grpc/grpc/blob/master/doc/server-reflection.md). It can be used to list and call gRPC methods using [swagger-ui](https://github.com/swagger-api/swagger-ui) conveniently. As gRPC-swagger is based on gRPC reflection, you only need to enable reflection feature when starting the service and no need modifying proto files and related code implementations. \n\n## Feature List\n\n* Easy to use, just need enable reflection when starting the service, without modifying protos and related implementations.\n* Integrated with swagger-ui, you can see the definitions of gRPC methods and parameters conveniently.\n* Simple to call gRPC method.\n\n## Screenshots\n\n![](doc/screenshots/01.png)\n\n![](doc/screenshots/02.png)\n\n\n## Live Demo\n\n[demo](http://ui.grpcs.top)\n\n## Build and Run\n### Use released jar\n```base\nwget https://github.com/grpc-swagger/grpc-swagger/releases/latest/download/grpc-swagger.jar \njava -jar grpc-swagger.jar\n```\n### Build from source\n```bash\nmvn clean package\njava -jar grpc-swagger-web/target/grpc-swagger.jar\n```\n\nBy default it will start at port 8080, use `--server.port=yourport` if\nyou want to use another port.\n```bash\njava -jar grpc-swagger-web/target/grpc-swagger.jar --server.port=8888\n```\n\n### Other parameters\n- `--enable.list.service=(true/false)` - Weather enable list registered services through listServices api. \n- `--service.expired.seconds=expiredSeconds` - If `expiredSeconds` is greater than 0, the registered service will be expired after `expiredSeconds` if no access.\n\n## How to use it\n1. Run gRPC-swagger, referring to [Build and Run](#build-and-run) \n2. Enable reflection when staring service. Below is a java example:  \n   add dependency to `pom.xml`:\n   ```xml\n   \u003cdependency\u003e\n       \u003cgroupId\u003eio.grpc\u003c/groupId\u003e\n       \u003cartifactId\u003egrpc-services\u003c/artifactId\u003e\n       \u003cversion\u003e${grpc.version}\u003c/version\u003e\n   \u003c/dependency\u003e\n   ```\n   enable reflection:\n   ```java\n   Server server = ServerBuilder.forPort(SERVER_PORT)\n       .addService(new HelloServiceImpl())\n       .addService(ProtoReflectionService.newInstance())\n       .build()\n       .start();\n   ``` \n3. Register endpoint. Open [this page](http://ui.grpcs.top/r.html), input necessary message and click register button, gRPC-swagger will automatically scan available services and return successful registered services when finished. You can click service link jump to ui page.\n\n![](doc/screenshots/register.png)\n \n4. Use swagger-ui to see gRPC services.\n5. Click `Try it out` button to have a test on the gRPC method.\n\n### Parameters\n- Request：the request data of gRPC，JSON format.\n- headers：metadata（header）passing to gRPC server，JSON format. Key represent header name，value represent header value.\n\n## API\n### Register Endpoint\n\nurl：`/register`\n\nparameters：\n* `host` - required, e.g. `localhost`\n* `port` - required, e.g. `12347`\n\nreturn example:\n```json \n{\n    \"code\": 1,\n    \"data\": [\n        {\n            \"service\": \"io.grpc.grpcswagger.showcase.HelloService\",\n            \"endPoint\": \"localhost:12347\"\n        }\n    ]\n}\n```\n\n### Services List\nurl: `/listServices`\n\nreturn example:\n```json \n{\n    \"code\": 1,\n    \"data\": [\n        {\n            \"service\": \"io.grpc.grpcswagger.showcase.HelloService\",\n            \"endPoint\": \"localhost:12347\"\n        }\n    ]\n}\n```\n\n### Call gRPC Method \nurl: `/{rawFullMethodName}`\n\nparameters：\n* `rawFullMethodName` - the full gRPC method name，e.g. `io.grpc.grpcswagger.showcase.HelloService.GetUser`\n* `payload` - gRPC method parameters，JSON format。 You can use `endpoint` parameter to specify the calling endpoint.\n\n### Swagger API\nurl： `/v2/api-docs`\n\nreturn data used by swagger-ui\n\nparameters：\n* service - full service name，e.g. `io.grpc.grpcswagger.showcase.HelloService`.\n\n## Acknowledgment\nThanks to the [polyglot](https://github.com/grpc-ecosystem/polyglot) project，The reflection related logic in our project is modified on polygolt.\n\n## Contribute\nFeel free to open an issue or pull request. We will appreciate it!\n\n## FAQ\n\n## License\n[MIT License.](/LICENSE)\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fgrpc-swagger%2Fgrpc-swagger","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fgrpc-swagger%2Fgrpc-swagger","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fgrpc-swagger%2Fgrpc-swagger/lists"}