This README contains the requirements and the steps to use protoapi ***If there are any inconsistencies, please refer to README.md for the latest version instead
- This project is based on the implementation of 'go'
- Objective: to automatically generate the base code of the frontend and backend API, saving development time
- Frontend generate TypeScript client code
- Backend currently supports code to generate java(spring framework) and go(echo framework)
- Current Version: 0.1.1
Install go 1.10 or above:
- Install go
- Make sure the $GOPATH is set accordingly
- Download the project code via:
go get github.com/yoozoo/protoapi
- Automatically initialize [protoc] (https://github.com/protocolbuffers/protobuf) with
protoapi:
protoapi init
-
help:
protoapi -h -
protoapi gen --lang=[language] [output directory] [proto file] -
Generate front-end TypeScript code:
protoapi gen --lang=ts [output_folder] [proto file path] -
Generate front-end PHP code:
protoapi gen --lang=php [output_folder] [proto file path] -
Generate backend Spring code:
protoapi gen --lang=spring [output_folder] [proto file path] -
Generate backend echo code:
protoapi gen --lang=echo [output_folder] [proto file path] -
Generate markdown code:
protoapi gen --lang=markdown [output_folder] [proto file path]
Example:
-
Generate front-end TypeScript code:
protoapi gen --lang=ts . ./test/proto/todolist.proto -
Generate backend Spring code:
protoapi gen --lang=spring . ./test/proto/todolist.proto -
For other related commands, please refer to [here] (docs/protoapi_cli.md)
- generator
- data (contains data structure)
- tpl/tpl.go
- data.go (defines shared data structures)
- output contains (the specific logic of code generation)
- echo_xx.go (supports code for generating echo)
- spring_xx.go (supports generating spring code)
- vue_ts.go (supports generating code for vue using ts)
- php.go (supports generating php code)
- markdown.go (supports generating markdown document)
- template (contains all template files)
- ts Xx.gots (TS template) Xx.govue (Vue template)
- echo_xx.gogo (go template corresponding to echo)
- spring_xx.gojava (java template corresponding to spring)
- php.gophp (php template)
- markdown.gomd (markdown template)
- generator.go (contains some shared code generation function logic)
- data (contains data structure)
- test (contains all the proto files generated by the test code)
- Writing tests
- Code review
- Other guidelines
- Add a new template to the generator/template folder:
- The specific syntax can be found in here
- Existing examples can refer to the existing templates in the generator/template
- The newly added template file is named after the suffix of the generated file. For example, if the ts file is generated, it is named: xxx.gots, and the generated java file is called xxx.gojava.
- Add a new xxx.go file in the generator/output folder or change the logic of an existing file
- Backend code can refer to generator/output/spring.go
- Front-end code can refer to generator/output/vue_ts.go
- For example, if you want to generate more ts files:
- Add a new template: generator/template/ts/example.gots
- Inside generator/output/ts.go
type tsGen struct {
// 1. Adding data
...
exampleFile string
...
exampleTpl *template.Template
}
...
/**
* Get TEMPLATE
*/
func (g *tsGen) loadTpl() {
...
// 2. Add an input template
g.exampleTpl = g.getTpl("/generator/template/ts/example.gots")
}
/**
* init filename with path
*/
func initFiles(packageName string, service *data.ServiceData) *tsGen {
gen := &tsGen{
...
// 3. Add generated file name
// The newly generated file will be named: example.ts, and which folder is generated according to packageName
// For example: packageName = yoozoo.protoconf.ts, the file will be generated with $output_dir/yoozoo/protoconf/ts
// packageName is defined in the proto file: "package yoozoo.protoconf.ts;"
exampleFile: genFileName(packageName, "example"),
}
return gen
}
func generateVueTsCode(applicationName string, packageName string, service *data.ServiceData, messages []*data.MessageData, enums []*data.EnumData, options []*data.Option) (map[string]string, error) {
...
/**
* combine data with template
*/
// 4. Finally, output the generated file
...
result[gen.exampleFile] = gen.genContent(gen.exampleTpl, dataMap)
...
}- Refer to [Create Execution File/Plugin] and [How to Use Plugin] to test the newly added template.
- Test existing proto sample files:
protoapi/test/hello.proto - or custom proto file test
- Test existing proto sample files:
syntax = "proto3"; // using syntax of proto3
option java_package = "com.yoozoo.spring"; //the generated java file will be in [output_folder]/com/yoozoo/spring folder
package com.yoozoo.ts; // the generated ts file will be in [output_folder]/com/yoozoo/ts folder
import "test/messages.proto"; // importing/using other proto file
// service definition
service HelloService {
rpc SayHello (HelloRequest) returns (HelloResponse);
}
- All API generated use HTTP POST by default
- Test using POST method using these apps or other similar apps:
- GET can be used in certain scenarios, but it is discouraged because the query string does not serialize complex request objects very well.