What is gRPC? Are you looking to integrate Swagger UI with gRPC? Here is a step-by-step guide to tell you.
What is gRPC
gRPC is an RPC-based framework designed for HTTP2. Therefore, the advantages of gRPC naturally include the advantages of HTTP2: Binary framing for data transmission, Multiplexing, Server push, and Header compression.
What is Swagger
Swagger is a specification and comprehensive framework for generating, describing, invoking, and visualizing RESTful-style web services. The overall goal is to enable clients and file systems to update at the same speed as the server. The methods, parameters, and models of the files are closely integrated into the server-side code, allowing the API to stay in sync consistently. Swagger makes deployment, management, and usage of powerful APIs more accessible than ever before.
How to enable Swagger for gRPC
Users familiar with gRPC should know that protocol buffer files need to be compiled into .go files using the relevant command-line tools.
Depending on the requirements, different command-line files may be used. Taking the Go language as an example, we generally need the following command-line tools.
In addition to installing the aforementioned command-line tools, we also need to run at least four different commands to compile *.proto files, which can be quite obscure and difficult to understand.
go get github.com/rookie-ninja/rk-boot
go get github.com/rookie-ninja/rk-grpc
# Please refer google.api.Http in https://github.com/googleapis/googleapis/blob/master/google/api/http.proto file for details.
- selector: api.v1.Greeter.Greeter
# protoc-gen-go needs to be installed, generate go files based on proto files
- name: go
# protoc-gen-go-grpc needs to be installed, generate grpc go files based on proto files
- name: go-grpc
# protoc-gen-grpc-gateway needs to be installed, generate grpc-gateway go files based on proto files
- name: grpc-gateway
# protoc-gen-openapiv2 needs to be installed, generate swagger config files based on proto files
- name: openapiv2
Apifdoghas launched the gRPC API debugging feature, and we will demonstrate how to create a new gRPC project in Apidog and debug the interface through a sample scenario.
Note: The gRPC interface management feature requires Apidog version 2.3.0 or higher.
Creating a gRPC Project in Apidog
Clicking on the "New Team" button, select the gRPC type, enter the project name, and then click on the "Create" button.
Import .proto File
To import the .proto file that defines the gRPC API's service, methods, and messages, you can either drag and drop the file or use the file's online URL in Apidog. Then click the "Add" button.
Apidog will generate the corresponding API information based on the content of the .proto file. The sample interface includes four types of method calls: Unary, Server Streaming, Client Streaming, and Bidirectional Streaming.
Initiate a Unary Call
Unary call sends one message in request and receives one message in response. gRPC uses Protocol Buffers for serialization, which is more efficient than JSON, and HTTP/2 as its transport protocol with HPACK compression algorithm for Header information, saving bandwidth. This makes it ideal for real-time responses or transmitting small data.
To initiate a unary call, select the "SayHello" method and enter "grpcb.in:9000" in the API address. Then click on the "Generate Automatically" button to generate the request body and click on "Invoke" to view the response.
As the icon suggests, Server Streaming means sending multiple response data in one request. For example, subscribing to all the transaction price data of stocks within one minute.
Bidirectional Streaming enables persistent bidirectional communication between clients and servers, allowing multiple messages to be transmitted simultaneously. It is commonly used in online games and real-time video call software, and is suitable for real-time communication and large-scale data transmission scenarios. After initiating the call, the client and server will maintain a session and receive real-time responses after sending different request contents.
gRPC API Collaboration
Apidog can render gRPC interface documents that are more suitable for human reading based on .proto files, making it easier to collaborate on interfaces within a team. You can click on the menu button on the right side of the interface to get the collaboration link and share it with other team members to align the debugging method of the interface.