GRPC: How to make GRPC provide Swagger UI?

introduce

This article will show you how to get a gRPC service to provide Swagger UI.

In order to provide Swagger UI, we first need gRPC to provide Restful apis, and then Swagger UI can access the background.

• To enable gRPC to provide REST APIS, we need to use grPC-Gateway
• We need to use protoc-gen-openapiv2 from proto file to create Swagger UI required file

Please visit the following address for the full tutorial:

• rkdev.info/cn
• Rkdocs.net lilify. app/cn (standby)

A prerequisite for

As anyone who has used GRPC should know, the protocol buffer requires compiling the *. Proto file into the *. Go file using the associated command line.

Depending on your needs, different command line files are used. Take the Go language as an example, we need the following command line files.

In addition to installing the above command line, we need to run at least four different commands to compile the *. Proto file as needed, which is quite obscure.

For details, please refer to my previous article: [GRPC: Using Buf to quickly compile GRPC proto files] or visit: [rkdev.info/cn/docs/boo…

The installation

go get github.com/rookie-ninja/rk-boot
Copy the code

Quick start

1. Create API/v1 / greeter. Proto

syntax = "proto3";

package api.v1;

option go_package = "api/v1/greeter";

service Greeter {
  rpc Greeter (GreeterRequest) returns (GreeterResponse) {}
}

message GreeterRequest {
  string name = 1;
}

message GreeterResponse {
  string message = 1;
}
Copy the code

2. Create the API/v1 / gw_mapping. Yaml

type: google.api.Service
config_version: 3

# Please refer google.api.Http in https://github.com/googleapis/googleapis/blob/master/google/api/http.proto file for details.
http:
  rules:
    - selector: api.v1.Greeter.Greeter
      get: /api/v1/greeter
Copy the code

3. Create buf. Yaml

version: v1beta1
name: github.com/rk-dev/rk-demo
build:
  roots:
    - api
Copy the code

4. Create buf. Gen. Yaml

version: v1beta1
plugins:
  # protoc-gen-go needs to be installed, generate go files based on proto files
  - name: go
    out: api/gen
    opt:
     - paths=source_relative
  # protoc-gen-go-grpc needs to be installed, generate grpc go files based on proto files
  - name: go-grpc
    out: api/gen
    opt:
      - paths=source_relative
      - require_unimplemented_servers=false
  # protoc-gen-grpc-gateway needs to be installed, generate grpc-gateway go files based on proto files
  - name: grpc-gateway
    out: api/gen
    opt:
      - paths=source_relative
      - grpc_api_configuration=api/v1/gw_mapping.yaml
  # protoc-gen-openapiv2 needs to be installed, generate swagger config files based on proto files
  - name: openapiv2
    out: api/gen
    opt:
      - grpc_api_configuration=api/v1/gw_mapping.yaml
Copy the code

5. Compile proto file

$ buf generate
Copy the code

The following files will be created.

$tree API/API/gen gen └ ─ ─ v1 ├ ─ ─ greeter. Pb. Go ├ ─ ─ greeter. Pb. Gw go ├ ─ ─ greeter. Swagger. Json └ ─ ─ greeter_grpc. Pb. Go 1 directory, 4 filesCopy the code

6. Create the boot. Yaml

grpc:
  - name: greeter                   # Name of grpc entry
    port: 8080                      # Port of grpc entry
    enabled: true                   # Enable grpc entry
    sw:
      enabled: true                 # Enable swagger
      jsonPath: "api/gen/v1"        # Provide swagger config file path
Copy the code

7. Create a main. Go

package main import ( "context" "fmt" "github.com/rookie-ninja/rk-boot" "github.com/rookie-ninja/rk-demo/api/gen/v1" "google.golang.org/grpc" ) // Application entrance. func main() { // Create a new boot instance. boot := rkboot.NewBoot() // *************************************** // ******* Register GRPC & Gateway ******* // *************************************** // Get grpc entry with name grpcEntry := boot.GetGrpcEntry("greeter") // Register grpc registration function grpcEntry.AddRegFuncGrpc(registerGreeter) // Register grpc-gateway registration function grpcEntry.AddRegFuncGw(greeter.RegisterGreeterHandlerFromEndpoint) // Bootstrap boot.Bootstrap(context.Background()) // Wait for shutdown sig boot.WaitForShutdownSig(context.Background()) } // Implementation of [type GrpcRegFunc func(server *grpc.Server)] func registerGreeter(server *grpc.Server) { greeter.RegisterGreeterServer(server, &GreeterServer{}) } // Implementation of grpc service defined in proto file type GreeterServer struct{} func (server *GreeterServer) Greeter(ctx context.Context, request *greeter.GreeterRequest) (*greeter.GreeterResponse, error) { return &greeter.GreeterResponse{ Message: fmt.Sprintf("Hello %s!" , request.Name), }, nil }Copy the code

8. Folder structure

$tree. ├ ─ ─ API │ ├ ─ ─ gen │ │ └ ─ ─ v1 │ │ ├ ─ ─ greeter. Pb. Go │ │ ├ ─ ─ greeter. Pb. Gw go │ │ ├ ─ ─ greeter. Swagger. Json │ │ ├── ├─ trash ├── ├─ trash ├── trash ├── trash ├── trash ├── trash ├─ trash ├─ trash ├─ trash ├─ trash ├─ trash ├─ trash ├─ trash ├─ trash ├─ trash ├─ trash ├─ trash ├─ trash ├─ trash ├─ trash ├─ trash ├─ trash ├─ trash ├─ trash ├─ trash ├─ trash ├─ trash ├─ trash ├─ trash ├─ trash ├─ trash ├─ trash ├─ trash ├─ trash └── Go. ├─ go. ├─ main. Go directories, 12 filesCopy the code

9. Verify

Visit Swagger: http://localhost:8080/sw