This generator is based on the OpenAPI 3.0 specification, and it is a very 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 than Swagger 2.0.
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 the OpenAPI 3.0 specification.
Note: currently, we support both OpenAPI 3.0 specification and Swagger 2.0 specification. There is a similar Swagger 2.0 generator tutorial available.
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
Optionality: optional Default: false
how environment-based variables should be generated
generatedgenerateEnvVars.generate:boolean whether the environment based variables should be generated.
If set to false, config files are copied to target folder (if different from source folder)
If set to true, config values are re-written to environment based
valuesgenerateEnvVars.skipArray: boolean whether Arrays in the config files should be re-written or not. This is considered false if not set.
generateEnvVars.skipMap: boolean whether Maps in the config files should be re-written or not. This is considered false if not set.
generateEnvVars.exclude: Array a list of files that should not be re-written
Note: This configuration option has been deprecated at 1.6.5 as it is not backward compatible.
specifies information required for generating openapi specifications from source code.
modelPackages: string the codegen tool can only generate specfication for models now. This config item specifies the package names of models in the class path. Mutliple package names are delimited by comma.
mergeTo: string If there is an existing openapi specification and users wants to merge the generated model sepcifications to it, this config item can be used to specify the location of the existing specification.
outputFormat: string Specifies the expected output format of the specification. Value can be yaml, json, or both
outputFilename: string the name of the generated openapi file. If not specified, the output file name is default to openapi_generated.
Here is an example of config.json for openapi generator.
In most of the 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
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 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.
Generate openapi specifications from source code (supports for code-first development)
To support code-first development, we provide the openapi specification generator to generate specifications from code. The command below demonstrates the usage of the specifcation generator.
Please note that the configuration item specGeneration is required to generate specifications. For details of this configuration item, please see Config.
java -cp .:./codegen-cli.jar:/path/to/project/target/classes com.networknt.codegen.Cli -f openapi-spec -o /path/to/config/config.json
To support generating parameterized config file, we provide additional commend -p, --parameterize for codegen-cli
By executing the above command, a project containing custom parameterized configuration files will be generated. Each configuration file that exists on the specified path examplePath/paramsCondig will be parameterized and added to the target configuration file path.
For more details of config parameterization, please see Config.
Docker Command Line
Above local build and command line utility works but it is very hard to use that in devops script. In order to make scripting easier, we have dockerized the command line utility.
The following command is using docker image to generate the code into /tmp/light-codegen/generated:
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
mvn clean install exec:exec
To test it.
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 openapi ~/networknt/model-config/rest/openapi/petstore/1.0.0 /tmp/petstore
Now you should have a project generated in /tmp/petstore/genereted