gRPC-swagger

中文文档

• What is gRPC-swagger
• Feature List
• Screenshots
• Live Demo
• Build and Run
  • Use released jar
  • Build from source
  • Other parameters
• How to use it
• API
  • Register Endpoint
  • Services List
  • Call gRPC Method
  • Swagger API
• Acknowledgment
• Contribute
• FAQ
• License

What is gRPC-swagger

gRPC-swagger is a gRPC debuggling tool developed based on gRPC reflection. It can be used to list and call gRPC methods using 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.

Feature List

• Easy to use, just need enable reflection when starting the service, without modifying protos and related implementations.
• Integrated with swagger-ui, you can see the definitions of gRPC methods and parameters conveniently.
• Simple to call gRPC method.

Screenshots

Live Demo

demo

Build and Run

Use released jar

wget https://github.com/grpc-swagger/grpc-swagger/releases/latest/download/grpc-swagger.jar 
java -jar grpc-swagger.jar

Build from source

mvn clean package
java -jar grpc-swagger-web/target/grpc-swagger.jar

By default it will start at port 8080, use --server.port=yourport if you want to use another port.

java -jar grpc-swagger-web/target/grpc-swagger.jar --server.port=8888

Other parameters

• --enable.list.service=(true/false) - Weather enable list registered services through listServices api.
• --service.expired.seconds=expiredSeconds - If expiredSeconds is greater than 0, the registered service will be expired after expiredSeconds if no access.

How to use it

1. Run gRPC-swagger, referring to Build and Run
2. Enable reflection when staring service. Below is a java example:
   add dependency to pom.xml:

   <dependency>
       <groupId>io.grpc</groupId>
       <artifactId>grpc-services</artifactId>
       <version>${grpc.version}</version>
   </dependency>

   enable reflection:

   Server server = ServerBuilder.forPort(SERVER_PORT)
       .addService(new HelloServiceImpl())
       .addService(ProtoReflectionService.newInstance())
       .build()
       .start();

3. Register endpoint. Open this page, 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.

4. Use swagger-ui to see gRPC services.
5. Click Try it out button to have a test on the gRPC method.

Parameters

• Request：the request data of gRPC，JSON format.
• headers：metadata（header）passing to gRPC server，JSON format. Key represent header name，value represent header value.

API

Register Endpoint

url：/register

parameters：

• host - required, e.g. localhost
• port - required, e.g. 12347

return example:

{
    "code": 1,
    "data": [
        {
            "service": "io.grpc.grpcswagger.showcase.HelloService",
            "endPoint": "localhost:12347"
        }
    ]
}

Services List

url: /listServices

return example:

{
    "code": 1,
    "data": [
        {
            "service": "io.grpc.grpcswagger.showcase.HelloService",
            "endPoint": "localhost:12347"
        }
    ]
}

Call gRPC Method

url: /{rawFullMethodName}

parameters：

• rawFullMethodName - the full gRPC method name，e.g. io.grpc.grpcswagger.showcase.HelloService.GetUser
• payload - gRPC method parameters，JSON format。 You can use endpoint parameter to specify the calling endpoint.

Swagger API

url： /v2/api-docs

return data used by swagger-ui

parameters：

• service - full service name，e.g. io.grpc.grpcswagger.showcase.HelloService.

Acknowledgment

Thanks to the polyglot project，The reflection related logic in our project is modified on polygolt.

Contribute

Feel free to open an issue or pull request. We will appreciate it!

FAQ

License

MIT License.