Swagger UI

Enable swagger UI for server.


In order to enable swagger, we need to enable grpc-gateway first.

Follow steps at prerequisite


go get github.com/rookie-ninja/rk-boot

General options

These are general options to start a grpc server with rk-boot

name description type default value Required
grpc.name The name of grpc server string “”, server won’t start Required
grpc.port The port of grpc server integer 0, server won’t start Required
grpc.enabled Enable grpc entry bool false Required
grpc.description Description of grpc entry. string "" Optional
grpc.enableReflection Enable grpc server reflection boolean false Optional
grpc.enableRkGwOption Enable RK style gateway server options. boolean false Optional
grpc.noRecvMsgSizeLimit Disable grpc server side receive message size limit boolean false Optional
grpc.gwMappingFilePaths The grpc gateway mapping file path []string [] Optional

Swagger options

name description type default value
grpc.sw.enabled Enable swagger service over gRpc server boolean false
grpc.sw.path The path access swagger service from web string /sw
grpc.sw.jsonPath Where the swagger.json files are stored locally string ""
grpc.sw.headers Headers would be sent to caller as scheme of [key:value] []string []

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;

2.Create 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.
    - selector: api.v1.Greeter.Greeter
      get: /api/v1/greeter

3.Create buf.yaml

version: v1beta1
name: github.com/rk-dev/rk-demo
    - api

4.Create buf.gen.yaml

version: v1beta1
  # protoc-gen-go needs to be installed, generate go files based on proto files
  - name: go
    out: api/gen
     - 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
      - 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
      - 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
      - grpc_api_configuration=api/v1/gw_mapping.yaml

5.Compile proto file

$ buf generate

There will be bellow files generated.

$ tree api/gen 
└── v1
    ├── greeter.pb.go
    ├── greeter.pb.gw.go
    ├── greeter.swagger.json
    └── greeter_grpc.pb.go
1 directory, 4 files

6.Create boot.yaml

  - name: greeter                   # Name of grpc entry
    port: 8080                      # Port of grpc entry
    enabled: true                   # Enable grpc entry
    enableRkGwOption: true          # Enable RK style server options
      - "api/v1/gw_mapping.yaml"    # Bootstrapper will look for gateway mapping files and load information into memory
      enabled: true                 # Enable swagger
      jsonPath: "api/gen/v1"            # Provide swagger config file path

7. Create main.go

package main

import (

// 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
    // Register grpc-gateway registration function

	// Bootstrap

	// Wait for shutdown sig

// 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

8.Full structure

$ tree
├── api
│   ├── gen
│   │   └── v1
│   │       ├── greeter.pb.go
│   │       ├── greeter.pb.gw.go
│   │       ├── greeter.swagger.json
│   │       └── greeter_grpc.pb.go
│   └── v1
│       ├── greeter.proto
│       └── gw_mapping.yaml
├── boot.yaml
├── buf.gen.yaml
├── buf.yaml
├── go.mod
├── go.sum
└── main.go

4 directories, 12 files


Swagger: http://localhost:8080/sw


Last modified October 29, 2021 : Update based on rk-boot@v1.2.8 (5f2c12b)