This generator is based on Swagger 2.0 specification and it is the most popular specification
format for Restful API these days. Although it might be replaced soon with OpenAPI 3.0, this
is still the main style in light-rest-4j framework. A lot of our customers are using it to
build their restful APIs. In light-rest-4j, we use the specification to scaffold the project
and we also use the specification during runtime for OAuth 2.0 scope verification and validation
against Swagger for Path Parameters, Query Parameters, Headers and Request Body if exists.
In light-rest-4j framework generator, the model that drives code generation is the Swagger 2.0
specification. When editing it, normally it will be in yaml format with separate files for
readability and flexibility. Before leverage it in light-rest-4j framework, all yaml files need
to be bundled and converted into json format in order to be consumed by the framework and generator.
Also, a validation needs to be done to make sure that the generated swagger.json is valid against
json schema of Swagger 2.0 specification.
name is used in generated pom.xml for project name
version is used in generated pom.xml for project vesion
groupId is used in generated pom.xml for project groupId
artifactId is used in generated pom.xml for project artifactId
rootPackage is the root package name for your project and it will normally be your domain plug project name.
handlerPackage is the Java package for all generated handlers.
modelPackage is the Java package for all generated models or POJOs.
overwriteHandler controls if you want to overwrite handler when regenerate the same project into the same folder. If you only want to upgrade the framework to another minor version and don’t want to overwrite handlers, then set this property to false.
overwriteHandlerTest controls if you want to overwrite handler test cases.
overwriteModel controls if you want to overwrite generated models.
httpPort is the port number of Http listener if enableHttp is true.
enableHttp to specify if the server listens to http port. Http should only be enabled in dev.
httpsPort is the port number of Https listener if enableHttps is true.
enableHttps to specify if the server listens to https port. Https should be used in any official environment for security reason.
enableRegistry to control if built-in service registry/discovery is used. Only necessary if running as standalone java -jar xxx.
enableParamDescription is to decide if generate parameter description from specifications as annotation.
supportDb to control if db connection pool will be setup in service.yml and db dependencies are included in pom.xml
dbInfo section is the database connection pool configuration info.
supportH2ForTest if true, add H2 in pom.xml as test scope to support unit test with H2 database.
supportClient if true, add com.networknt.client module to pom.xml to support service to service call.
In most of the cases, developers will only update handlers, handler tests and models in a project.
Of course, you might need different database for your project and we have a database tutorial that
can help you to further config Oracle and Postgres.
Given we have most of our model and config files in model-config repo, most generator input would
from the rest folder in model-config for light-rest-4j framework.
Let’s clone the project to your workspace as we will need it in the following steps.
I am using ~/networknt as workspace but it can be anywhere in your home directory.
You can use docker run command to call the generator but it is very complicated for the parameters.
In order to make things easier and friendlier to devops flow. Let’s create a script to call the
command line from docker image.
If you look at the docker run command you can see that we basically need one input folder for
schema and config files and one output folder to generated code. Once these volumes are mapped to
local directory and with framework specified, it is easy to derive other files based on convention.
./generate.sh swagger ~/networknt/model-config/rest/swagger/petstore/2.0.0 /tmp/petstore
Now you should have a project generated in /tmp/petstore/genereted
The service API is ready. We are working on the UI with a generation wizard.