This generator is based on the OpenAPI 3.0 specification, and it is a new specification that is supposed to replace Swagger 2.0 specification. It has some significant changes to enhance the spec definition and simply the validate with only JSON schema. In my opinion, it is much easier to use, and the implementation is much simpler then Swagger 2.0. OpenAPI adds a number of features as well. The only issue I can see is the entire toolchains around Swagger 2.0 are not migrated to OpenAPI 3.0 yet, and we have to build our own openapi-parser for parsing and validation.
In light-rest-4j framework generator, the model that drives code generation is the OpenAPI 3.0 specification previously named Swagger specification. When editing it, it usually will be in YAML format with separate files for readability and flexibility. Before leverage it in the light-rest-4j framework, all YAML files need to be bundled to a single file in YAML or JSON format to be consumed by the framework and generator. Also, validation needs to be done to make sure that the openapi.yaml or openapi.json is valid against JSON schema of OpenAPI 3.0 specification.
Note: we only support OpenAPI 3.0 specification for Kotlin.
OpenAPI Bundler - A command line tool to combine multiple yaml specifications into one
Here is a reference table for the example config.json below:
Used in generated prom.xml for project name
Used in generated pom.xml for project version
Used in generated pom.xml for project groupId
used in generated pom.xml for project artifactId
root package name for your project and it will normally be your domain plug project name. Optionality: optional
the Java package for all generated handlers.
the Java package for all generated models or POJOs.
controls if you want to overwrite handler when regenerating the same project into the same folder. Optionality: mandatory Recommendation: set to false if you only want to upgrade the framework to another minor version and don’t want to overwrite handlers
controls if you want to overwrite handler test cases.
controls if you want to overwrite generated models.
Optionality: mandatory Recommendation: set to false to prevent the model classes being overwritten
controls whether you wish to generate only the model classes
Optionality: optional Recommendation: to be used by teams consuming an API and who wish to generate the model classes only Default: false
controls whether you wish to regenerate only the model and handler classes, while skipping the underlying scripts, pom.xml and other files
Optionality: optional Recommendation: to be used when there are changes in the model and teams wish to regenerate only artifacts affected by the change: model, handler classes, and handler.yml Default: false
controls whether a values.yml is to be generated, with commonly changed values across test and production environments Default: false
the port number of Http listener if enableHttp is true
specify if the server listens to http port.
Optionality: mandatory Recommendation: Http should be enabled in dev
the port number of Https listener if enableHttps is true.
specify if the server listens to https port.
Optionality: mandatory Recommendation: Https should be used in any official environment for security reason Note: when Https is enabled, Http will automatically be disabled
specify if the server supports HTTP/2 connection.
Optionality: mandatory Recommendation: Should always be set to true
control if built-in service registry/discovery is used
Optionality: mandatory Note: Only necessary if running as standalone java -jar xxx
decide if generate parameter description from specifications as annotation.
Optionality: optional Default: true
control if db connection pool will be setup in service.yml and db dependencies are included in pom.xml
database connection pool configuration info
if true, add H2 in pom.xml as test scope to support unit test with H2 database.
if true, add com.networknt.client module to pom.xml to support service to service call.
decides whether to enable the health check in the handler chain and expose the health check endpoint. Set to true to skip the wiring of the health check
Optionality: optional Default: false
decides whether to wire the server info in the handler chain and expose the server info endpoint. Set to true to skip the wiring of the server info retrieval
Optionality: optional Default: false
decides whether to wire the Prometheus metrics collection handler in the handler chain. Set to true to skip the wiring of the Prometheus metrics collection handler
In most cases, developers will only update handlers, handler tests, and models in a generated project. Of course, you might need a 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 come from the rest folder in model-config for the 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 a workspace, but it can be anywhere in your home directory.
git clone https://github.com/networknt/model-config.git
The default format for OpenAPI 3.0 specification is YAML. Given we have test openapi.yaml and config.json in light-rest-4j/src/test/resources folder, the following command line will generate a RESTful API at /tmp/openapi-yaml folder.
Please note that you need to use a raw URL when accessing GitHub files. The above command line will generate a petstore service in /tmp/openapi-petstore.
Given we have most of the model and config files in the model-config repo, most generator input would from the rest folder in model-config. Here is the example to generate petstore. Assuming model-config is in the same workspace as light-codegen.
On Linux environment, the generated code might belong to root:root and you need to change the owner to yourself before building it.
sudo chown -R steve:steve generated
./gradlew clean build run
To test it.
You can use docker run command to call the generator, but it is very complicated for the parameters. To make things easier and friendlier to DevOps flow. Let’s create a script to call the command line from a 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 generate code. Once these volumes are mapped to a local directory and with framework specified, it is easy to derive other files based on
./generate.sh openapikotlin ~/networknt/model-config/rest/openapi/petstore/1.0.0 /tmp/petstore
Now you should have a project generated in /tmp/petstore/genereted