{"id":13459989,"url":"https://github.com/fullstorydev/grpcui","last_synced_at":"2025-05-12T05:17:16.930Z","repository":{"id":37613786,"uuid":"160253491","full_name":"fullstorydev/grpcui","owner":"fullstorydev","description":"An interactive web UI for gRPC, along the lines of postman","archived":false,"fork":false,"pushed_at":"2025-04-09T14:59:53.000Z","size":8568,"stargazers_count":5503,"open_issues_count":70,"forks_count":393,"subscribers_count":59,"default_branch":"master","last_synced_at":"2025-05-12T02:43:18.743Z","etag":null,"topics":["golang","grpc","postman"],"latest_commit_sha":null,"homepage":null,"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/fullstorydev.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}},"created_at":"2018-12-03T21:03:58.000Z","updated_at":"2025-05-11T18:57:45.000Z","dependencies_parsed_at":"2023-10-12T06:44:17.906Z","dependency_job_id":"a1e3f00c-8ef0-4be3-a2f5-76420c7d4021","html_url":"https://github.com/fullstorydev/grpcui","commit_stats":{"total_commits":160,"total_committers":29,"mean_commits":5.517241379310345,"dds":0.59375,"last_synced_commit":"b0c061d0983ab3aa0ed874e9888790a246121b9c"},"previous_names":[],"tags_count":16,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/fullstorydev%2Fgrpcui","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/fullstorydev%2Fgrpcui/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/fullstorydev%2Fgrpcui/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/fullstorydev%2Fgrpcui/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/fullstorydev","download_url":"https://codeload.github.com/fullstorydev/grpcui/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":253672676,"owners_count":21945479,"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":["golang","grpc","postman"],"created_at":"2024-07-31T10:00:33.526Z","updated_at":"2025-05-12T05:17:16.908Z","avatar_url":"https://github.com/fullstorydev.png","language":"Go","readme":"# gRPC UI\n[![Build Status](https://circleci.com/gh/fullstorydev/grpcui/tree/master.svg?style=svg)](https://circleci.com/gh/fullstorydev/grpcui/tree/master)\n[![Go Report Card](https://goreportcard.com/badge/github.com/fullstorydev/grpcui)](https://goreportcard.com/report/github.com/fullstorydev/grpcui)\n\n`grpcui` is a command-line tool that lets you interact with gRPC servers via a browser.\nIt's sort of like [Postman](https://www.getpostman.com/), but for gRPC APIs instead of\nREST.\n\nIn some ways, this is like an extension to [grpcurl](https://github.com/fullstorydev/grpcurl).\nWhereas `grpcurl` is a command-line interface, `grpcui` provides a web/browser-based\nGUI. This lets you interactively construct requests to send to a gRPC server.\n\nWith this tool you can also browse the schema for gRPC services, which is presented as a\nlist of available endpoints. This is enabled either by querying a server that supports\n[server reflection](https://github.com/grpc/grpc/blob/master/src/proto/grpc/reflection/v1/reflection.proto),\nby reading proto source files, or by loading in compiled \"protoset\" files (files that contain\nencoded file [descriptor protos](https://github.com/google/protobuf/blob/master/src/google/protobuf/descriptor.proto)).\nIn fact, the way the tool transforms JSON request data into a binary encoded protobuf\nis using that very same schema. So, if the server you interact with does not support\nreflection, you will either need the proto source files that define the service or need\nprotoset files that `grpcui` can use.\n\nThis repo also provides two library packages\n1. `github.com/fullstorydev/grpcui`: This package contains the building blocks for embedding a\n   gRPC web form into any Go HTTP server. It has functions for accessing the HTML form, the\n   JavaScript code that powers it, as well as a sample CSS file, for styling the form.\n2. `github.com/fullstorydev/grpcui/standalone`: This package goes a step further and supplies\n   a single, simple HTTP handler that provides the entire gRPC web UI. You can just wire this\n   handler into your HTTP server to embed a gRPC web page that looks exactly like the one you\n   see when you use the `grpcui` command-line program. This single handler uses the above\n   package but also supplies the enclosing HTML page, some other script dependencies (jQuery\n   and jQuery-UI), and additional CSS and image resources.\n\n## Features\n`grpcui` supports all kinds of RPC methods, including streaming methods. However, it requires\nyou to construct the entire stream of request messages all at once and then renders the entire\nresulting stream of response messages all at once (so you can't interact with bidirectional\nstreams the way that `grpcurl` can).\n\n`grpcui` supports both plain-text and TLS servers and has numerous options for TLS\nconfiguration. It also supports mutual TLS, where the client is required to present a\nclient certificate.\n\nAs mentioned above, `grpcui` works seamlessly if the server supports the reflection\nservice. If not, you can supply the `.proto` source files or you can supply protoset\nfiles (containing compiled descriptors, produced by `protoc`) to `grpcui`.\n\nThe web UI allows you to set request metadata in addition to defining the request message data.\nWhen defining request message data, it uses a dynamic HTML form that supports data entry for\nall possible kinds of protobuf messages, including rich support for well-known types (such as\n`google.protobuf.Timestamp`), one ofs, and maps.\n\nIn addition to entering the data via HTML form, you can also enter the data in JSON format,\nby typing or pasting the entire JSON request body into a text form.\n\nUpon issuing an RPC, the web UI shows all gRPC response metadata, including both headers and\ntrailers sent by the server. And, of course, it shows a human-comprehensible response body, in\nthe form of an HTML table.\n\n## Installation\n\n### Homebrew (MacOS or Linux)\nInstall with `homebrew`:\n```shell\nbrew install grpcui\n```\n\n### From Source\nYou can use the `go` tool to install `grpcui`:\n```shell\ngo install github.com/fullstorydev/grpcui/cmd/grpcui@latest\n```\n\nThis installs the command into the `bin` sub-folder of wherever your `$GOPATH`\nenvironment variable points. If this directory is already in your `$PATH`, then\nyou should be good to go.\n\nIf you have already pulled down this repo to a location that is not in your\n`$GOPATH` and want to build from the sources, you can `cd` into the repo and then\nrun `make install`.\n\nIf you encounter compile errors, you could have out-dated versions of `grpcui`'s\ndependencies. You can update the dependencies by running `make updatedeps`.\n\n### Running without install\n\n```\ngo run ./cmd/grpcui/grpcui.go -plaintext localhost:9019\n```\n\n## Usage\nThe usage doc for the tool explains the numerous options:\n```shell\ngrpcui -help\n```\n\nMost of the flags control how the program connects to the gRPC server that to which\nrequests will be sent. However, there is one flag that controls `grpcui` itself: the\n`-port` flag controls what port the HTTP server should use to expose the web UI. If\nno port is specified, an ephemeral port will be used (so likely a different port each\ntime it is run, allocated by the operating system).\n\n### Web Form\nWhen you run `grpcui`, it will show you a URL to put into a browser in order to access\nthe web UI.\n\n```\n$ grpcui -plaintext localhost:12345\ngRPC Web UI available at http://127.0.0.1:60551/...\n\n```\n\nWhen you navigate to this URL, you are presented with the user interface:\n\n\u003cp align=\"center\"\u003e\n  \u003cimg alt=\"web UI screenshots\" width=\"888\" src=\"doc-images/grpc-web-ui.png\"\u003e\n\u003c/p\u003e\n\nThe top two listboxes allow you to select the service and method of the RPC to issue.\nOnce a selection is made, the panel below will show a form that allows you to define an\nRPC request. The form is constructed, dynamically, based on the actual request message\nstructure of the selected RPC.\n\nYou'll notice a second tab that lets you view (and edit) the raw JSON value for the\nrequest data. This can be useful to copy+paste a large request message, without having\nto point-and-click to define each field value, one at a time.\n\nThe third tab shows the response data. This tab is grayed out and disabled until you\nactually click the \"Invoke\" button, which can be found at the bottom of the page.\n\n### Request Form\nThe first thing to note about the form is that it will generally be a table, where each row\nis a field. The table has three important columns:\n\n1. The first column shows the name and type of the field.\n2. The second columns indicates the \"cardinality\" of the field. Typical fields are\n   optional. The second column for optional fields is a checkbox indicating whether the\n   field is present or not. If the field is not present, its default value is assumed.\n   Repeated fields show buttons in this column for adding and deletig values. The green\n   \"+\" allows you to add values to the repeated field. The red \"x\" next to a value will\n   remove that value. Finally, if the field is required (only supported in syntax\n   \"proto2\"), the column will contain only an asterisk.\n3. The third column shows the value of the field. If the field is absent, this will show\n   the default value for the field. Fields that are nested messages show \"unset\", but\n   scalar types show their default (usually the type's zero value, but default values are\n   configurable when using syntax \"proto2\"). Absent fields are also not editable -- you\n   must first check the box in column two to make the field present before editing its\n   value. Repeated fields show a nested table that occupies columns two and three and\n   allows for adding and removing values.\n\nFields whose type is a nested message will include a nested table in column three. This\nnested table has its own three columns and one row per field therein.\n\nOne-ofs are rendered a little differently. Instead of two columns indicating the presence\nand value of the field, they include a nested table showing all of the possible fields\nin the one-of. However, the middle column is a radio button instead of a checkbox, so that\nonly one of the fields can be present at any given time. In addition to a row for each\nfield in the one-of, there is also an option named *None*, which indicates a one-of where\nno value is set.\n\nHere's an example form for a message that has two required fields (`id` and `name`), one\nrepeated field (`labels`), a handful of normal optional fields, and a single one-of that\nhas four options. In the first image, no values are present (except, of course, for the\nrequired fields at the top). In the second, several field values are present.\n\n\u003cp align=\"center\"\u003e\n  \u003cimg alt=\"web UI message fields\" width=\"408\" align=\"top\" src=\"doc-images/fields.png\"\u003e\n  \u003cimg alt=\"web UI message fields, with some values\" width=\"420\" align=\"top\" src=\"doc-images/fields-filled-out.png\"\u003e\n\u003c/p\u003e\n\nFor RPCs that accept a *stream* of requests, the web form allows the user to define multiple\nmessages in the stream. It defaults to a single request, but the user can remove it to send none\nor can send many. A stream resembles a repeated field, but the repeated \"thing\" is the entire\nrequest:\n\n\u003cp align=\"center\"\u003e\n  \u003cimg alt=\"web UI request stream\" width=\"380\" src=\"doc-images/streams-repeated.png\"\u003e\n\u003c/p\u003e\n\nThat last example also shows how well-known message types get special treatment. In that example,\nthe request type is `google.protobuf.StringValue`. Instead of showing a form for a message with a\nsingle field named `value` with type `string`, the UI is simple and the \"boxing\" ceremony is\nelided. It instead just shows a simple textbox for entering the string value.\n\nA more interesting example of how well-known message types are treated is `google.protobuf.Timestamp`,\nwhere a date picker is shown:\n\n\u003cp align=\"center\"\u003e\n  \u003cimg alt=\"web UI request stream\" width=\"640\" src=\"doc-images/timestamp.png\"\u003e\n\u003c/p\u003e\n\n### Raw Request JSON\nThe second tab lets you view the JSON representation of the request data you have defined on the\nfirst tab. You can also directly edit the JSON data -- including pasting in an entire JSON message.\n\nThe JSON representation uses the standard [JSON mapping for Protocol Buffers](https://developers.google.com/protocol-buffers/docs/proto3#json).\n\n\u003cp align=\"center\"\u003e\n  \u003cimg alt=\"web UI request JSON\" width=\"600\" src=\"doc-images/raw-json.png\"\u003e\n\u003c/p\u003e\n\nWhen working with an RPC that has a streaming request, the JSON data will be a JSON array, where\neach element is a single message in the stream.\n\n### Responses\nWhen the \"Invoke\" button is pressed, the request data is sent to the server and the selected RPC\nmethod is invoked. The web form will then navigate to the third tab to show the server's response.\n\nThe response tab has three sections:\n\n1. Response Headers: Any response header metadata is shown here.\n2. Response Data: Any response messages are shown here as are any error messages. RPC methods with\n   a streaming response may show both message data *and* an error. Error messages show the gRPC\n   status code and the server-defined message text.\n3. Response Trailers: Finally, any response trailer metadata is shown.\n\n\u003cp align=\"center\"\u003e\n  \u003cimg alt=\"web UI response\" width=\"500\" src=\"doc-images/response.png\"\u003e\n\u003c/p\u003e\n\nEach of these three sections is a table of data. Response messages are the most interesting, and\ntheir structure closely resembles how messages are structured on the \"Request Form\" tab. Fields that\nhave nested messages will include a nested table.\n\n## Descriptor Sources\nThe `grpcui` tool can operate on a variety of sources for descriptors. The descriptors\nare required, in order for `grpcui` to understand the RPC schema, translate inputs\ninto the protobuf binary format as well as translate responses from the binary format\ninto text. The sections below document the supported sources and what command-line flags\nare needed to use them.\n\n### Server Reflection\nWithout any additional command-line flags, `grpcui` will try to use [server reflection](https://github.com/grpc/grpc/blob/master/src/proto/grpc/reflection/v1/reflection.proto).\n\nExamples for how to set up server reflection can be found [here](https://github.com/grpc/grpc/blob/master/doc/server-reflection.md#known-implementations).\n\n### Proto Source Files\nTo use `grpcui` on servers that do not support reflection, you can use `.proto` source\nfiles.\n\nIn addition to using `-proto` flags to point `grpcui` at the relevant proto source file(s),\nyou may also need to supply `-import-path` flags to tell `grpcui` the folders from which\ndependencies can be imported.\n\nJust like when compiling with `protoc`, you do *not* need to provide an import path for the\nlocation of the standard protos included with `protoc` (which contain various \"well-known\ntypes\" with a package definition of `google.protobuf`). These files are \"known\" by `grpcui`\nas a snapshot of their descriptors is built into the `grpcui` binary.\n\n### Protoset Files\nYou can also use compiled protoset files with `grpcui`. Protoset files contain binary\nencoded `google.protobuf.FileDescriptorSet` protos. To create a protoset file, invoke\n`protoc` with the `*.proto` files that define the service:\n\n```shell\nprotoc --proto_path=. \\\n    --descriptor_set_out=myservice.protoset \\\n    --include_imports \\\n    my/custom/server/service.proto\n```\n\nThe `--descriptor_set_out` argument is what tells `protoc` to produce a protoset,\nand the `--include_imports` argument is necessary for the protoset to contain\neverything that `grpcui` needs to process and understand the schema.\n","funding_links":[],"categories":["Go","Misc","开发","语言资源库","Web-Based","Specialized API Clients (GraphQL, gRPC, WebSocket)","Projects","RPC","Language-Specific","JavaScript","Identifiers","网络信息服务"],"sub_categories":["go","59. [gRPC UI](https://github.com/fullstorydev/grpcui)","API Testing","Go","GUI - other","网络协议"],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ffullstorydev%2Fgrpcui","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Ffullstorydev%2Fgrpcui","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ffullstorydev%2Fgrpcui/lists"}