Openapi to GRPC within Spring Environment via Maven

Because GRPC is the future? xD

Build Flow

Why this article would help?

1. You need to integrate GRPC with your spring micro-service /s.
2. You want to have tool chain that could generate and build grpc-java from openapi spec in java via maven.
3. Integrate with your CI / CD with minimal to no amount of manual intervention.

Flow

1. Gnostic-grpc is built using go. We need to use golang wrapper maven plugin to get this set up and run (https://github.com/raydac/mvn-golang)
2. Then from the .proto definition we will convert to grpc java stub using xoltice protobuf maven plugin (https://www.xolstice.org/protobuf-maven-plugin/usage.html)
3. We can utilize maven executions and phases to sequence the steps and build into complete server / client stubs and intergrate them into CI/CD.
4. Multiple maven plugins are used to achieve this. More details can be found below in Components section.

Components

In general we will anchor our build flow with maven. Utilizing the maven’s phases and goals, we sequence the build steps in order to output a grpc java classes from openapi spec document.

Though there will be intermediary files to achieve that (IE, .proto, pbs and others) which we can ignore.

Gnostic and Gnostic GRPC

A golang tool to convert from openapi to proto definition. More complete than openapi proto generator.

https://github.com/google/gnostic-grpc

Though both still can’t handle type mapping cases (https://openapi-generator.tech/docs/usage/#type-mappings-and-import-mappings).

In case your project uses type mappings, it’s better to regenerate the openapi document using other tools and then use this newly generated openapi doc to convert to .proto definition.

Maven Golang Wrapper Plugin

The plugin will setup go env within your maven target directory.

1. Setup go sdk.
2. Install the libraries needed (gnostic and gnostic-grpc)
3. Run gnostic-grpc to convert the openapi doc to .proto.

https://github.com/raydac/mvn-golang

Maven Ant Plugin

Proto generated from gnostic will be 1 big class with package named after the filename of the openapi file by default.

By using the ant plugin, we can use replace task to add java_multiple_files and java_package options in the proto file. Without these 2, you will generated single file which could get very big with default package name.

The pattern we use will be as follows:

<target>
  <replace file="${project.basedir}/src/main/resources/protodefs/openapiexample.proto" token="import &quot;google/protobuf/empty.proto&quot;;"
      value="import &quot;google/protobuf/empty.proto&quot;;${line.separator}${line.separator}option java_multiple_files = true;${line.separator}option java_package = &quot;org.maz.grpc&quot;;"/>
</target>

It will replace “import google/protobuf/empty.proto” string with

import "google/protobuf/empty.proto";

option java_multiple_files = true;
option java_package = "org.maz.grpc";

Go Workaround Driven Development (WDD™) xD.

https://maven.apache.org/plugins/maven-antrun-plugin/

Maven Protobuf Plugin

This will convert proto definition into java grpc classes.

https://www.xolstice.org/protobuf-maven-plugin/

Lognet GRPC Spring Starer

Provides the implementation of the grpc, integrated with spring. All those spring goodness such as ExceptionHandler, Interceptors (intercept incoming grpc call), validation integration, all those goodness etc.)

https://github.com/LogNet/grpc-spring-boot-starter

Improvement

1. For the steps to convert from openapi to proto, we don’t have to run it all the time. Only when there’re changes on our openapi doc, we’ll need to run it. Hence, this step can be put within maven profile (triggered when needed)
2. We can enhance further by using schema registry such as confluent schema registry or aws glue to allow distribution of the definition (proto) across producers and consumers. Else (we can also make the definition into maven artifact which can be shared across services)

Conclusion

This flow would help to better integrate your tool chain with grpc build process.

Not only this is inline with proper engineering practices, using architecture such as microservices would make this build process a must to ensure the overhead of managing the services minimal (enables build, verification and test automation).

Souce code can be found at https://github.com/MazizEsa/spring-grpc-maven-example