中文文档

• 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

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.

• 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.

demo

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

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

• --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.

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.

• 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.

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"
        }
    ]
}

url: /listServices

return example:

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

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.

url： /v2/api-docs

return data used by swagger-ui

parameters：

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

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

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

MIT License.