This generator is based on 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 then Swagger 2.0.
OpenAPI adds a number of features 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-parse] 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: currently, we support both OpenAPI 3.0 specification and Swagger 2.0 specification. There is a similar Swagger 2.0 generator tutorial available.
generateEnvVars.generate:boolean whether the environment based variables should be generated. This is considered false if not set.
If this is set to false, config files are copied to target folder (if it is different from source folder).
If this is set to true, config values are re-written to environment based values.
generateEnvVars.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
specGeneration 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.
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
Java Command line
Before using the command line to generate the code, you need to check out the light-codegen repo and build it. I am using ~/networknt as the workspace, but it can be anywhere in your home directory.
git clone https://github.com/networknt/light-codegen.git
mvn clean install
Given we have test openapi.json and config.json in light-rest-4j/src/test/resources folder, the following command line will generate a RESTful API at /tmp/openapi-json 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 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 congiration 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
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
./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
The service API is ready. We are working on the UI with a generation wizard.