restgen

module
Version: v1.0.1 Latest Latest
Warning

This package is not in the latest version of its module.

Go to latest
Published: Apr 21, 2020 License: MIT

README

restgen

Build Status GoDoc

restgen is a plugin for protocol buffer compiler. It generates go code for REST endpoints, based on Google's Protocol Buffers (a.k.a. protobuf).

Installation

This tool is written in go. You need a working go installation to install it. Execute the following command in a terminal:

go install github.com/doozer-de/restgen/protoc-gen-bff

This installs the protobuf compiler plugin protoc-gen-bff (where "bff" is an abbreviation for "backend for frontend"). It must be in your $PATH for the protocol compiler to find it.

Usage

  1. Define a service in your protobuf. Every service will be defined with a service map and rpc methods.

A service map definition looks like the following:

	option (pbmap.service_map) = {
		version: "1"
		base_uri: "/base_uri/"
		target_package: "samplesvc"
	};

This service map is defined in pbmap/map.proto:

  • version:
  • base_uri: defines the base URI, e. g. http://[address]/[base_uri]/[path]...
  • target_package: defines the name of the package, where the generated file will be placed. This option doesn't affect the location of the file - this has to be defined with OUT_DIR in the protoc command operand --bff_out=OUT_DIR

A rpc method would be defined like the following:

	rpc Methodname(RequestMethod) returns (ResponseMethod) {
		option (pbmap.method_map) = {
            method: "method"
            path: "/[path]/:id"
            query_string: "key=[message].[field]:[data_type]"
            body: "*"
        };
    }

The method map is defined in pbmap/map.proto.

Explanation:

  • method: defines the used HTTP method, supported are: Get, Put, Post, Delete
  • path: identifies the method, has to be unique in this service and has to be compatible with Julian Schmidt's HTTP Router; Format a/b/:c/:d where a/b/ are fixed and :c and :d are parameters mapped to C and D in the underlying GRPC Request
  • query_string: Format "key1=:var1&key=:var2": they keys will be mapped to the variables var1, var2 of the unterlying GRPC Request
  • body: indicates, if the request has a body or not
  1. The messages are defined as usual

  2. Compile the protobuf.

  3. Execute the following command in a terminal:

protoc [OPTION] --bff_out=OUT_DIR PROTO_FILES

Features

Supported

  • atomic datatypes
  • maps
  • user defined messages; inside of the same package and outside of this package)
  • HTTP Methods: Get, Put, Post, Delete
  • path parameter; also with deep paths
  • query strings; also with deep paths

Not supported

  • enums in path parameter and query strings

Example

You can find a sample protobuf definition in samplesvc/pb/samplesvc.proto and the generated code in samplesvc/samplesvc_gen.go.

Directories

Path Synopsis
Package protoc-gen-bff implements a plugin to generate go code for REST endpoints from protocol buffer files.
Package protoc-gen-bff implements a plugin to generate go code for REST endpoints from protocol buffer files.
emitters
Package emitters generates go-specific code.
Package emitters generates go-specific code.
Package registry structures the protobuf defined types and provides them to generate code.
Package registry structures the protobuf defined types and provides them to generate code.
pb
Package pb is a generated protocol buffer package.
Package pb is a generated protocol buffer package.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
t or T : Toggle theme light dark auto
y or Y : Canonical URL