OpenAPI Lambda Generator

This generator is based on the OpenAPI 3.0 specification to generate one AWS Lamdbd function per endpoint. Also, it generates all the artifacts for the building and deploying with cloud formation YAML files.

Input

Model

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 leveraging 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 only the OpenAPI 3.0 specification and Swagger 2.0 specification support was removed.

• Swagger Editor

• Swagger CLI

Config

Here is an example of config.json for openapi generator.

{
  "projectName": "petstore",
  "version": "1.0.1",
  "groupId": "com.networknt",
  "artifactId": "petstore",
  "rootPackage": "com.networknt.petstore",
  "handlerPackage":"com.networknt.petstore.handler",
  "modelPackage":"com.networknt.petstore.model",
  "useLightProxy": true,
  "launchType": "EC2",
  "publicVpc": true,
  "packageDocker": false,
  "region": "us-east-2",
  "overwriteHandler": true,
  "overwriteHandlerTest": true,
  "overwriteModel": true,
  "enableRegistry": false,
  "generateModelOnly": false
}

Given we have most of our model and config files in model-config repo, most generator input would come from the lambda folder in model-config for the light-aws-lambda 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.

cd ~/networknt
git clone https://github.com/networknt/model-config.git

Usage

Java Command line

You can download or build the codegen-cli command line jar.

• JSON Model

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-lambda folder.

Working directory: light-codegen

cd ~/networknt/light-codegen
java -jar codegen-cli/target/codegen-cli.jar -f openapilambda -o /tmp/openapi-lambda -m light-rest-4j/src/test/resources/openapi.json -c light-rest-4j/src/test/resources/config.json

After you run the above command, you can build and start the service:

cd /tmp/openapi-lambda

To test the service from another terminal:

curl http://localhost:8080/server/info

• YAML Model

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.

Working directory: light-codegen

cd ~/networknt/light-codegen
java -jar codegen-cli/target/codegen-cli.jar -f openapi -o /tmp/openapi-yaml -m light-rest-4j/src/test/resources/openapi.yaml -c light-rest-4j/src/test/resources/config.json

After you run the above command, you can build and start the service:

cd /tmp/openapi-yaml
mvn clean install exec:exec

To test the service from another terminal:

curl http://localhost:8080/server/info

The above example use local OpenAPI specification and config file. Let’s try to use files from github.com:

Working directory: light-codegen

rm -rf /tmp/openapi-petstore
cd ~/networknt/light-codegen
java -jar codegen-cli/target/codegen-cli.jar -f openapi -o /tmp/openapi-petstore -m https://raw.githubusercontent.com/networknt/model-config/master/rest/openapi/petstore/1.0.0/openapi.json -c https://raw.githubusercontent.com/networknt/model-config/master/rest/openapi/petstore/1.0.0/config.json

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.

Working directory: networknt

rm -rf /tmp/openapi-petstore
cd ~/networknt
java -jar light-codegen/codegen-cli/target/codegen-cli.jar -f openapi -o /tmp/openapi-petstore -m model-config/rest/openapi/petstore/1.0.0/openapi.json -c model-config/rest/openapi/petstore/1.0.0/config.json

• 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.

cd ~/networknt/light-codegen/code-cli/target
java -cp .:./codegen-cli.jar:/path/to/project/target/classes com.networknt.codegen.Cli -f openapi-spec -o /path/to/config/config.json

Config Parameterization

To support generating parameterized config file, we provide additional commend -p, --parameterize for codegen-cli

cd ~/networknt/light-codegen
java -jar codegen-cli/target/codegen-cli.jar -p examplePath/paramsCondig -f openapilambda -o /tmp/openapi-json -m light-rest-4j/src/test/resources/openapi.json -c light-rest-4j/src/test/resources/config.json

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.

Codegen Site

You can generate a Lambda project from the site https://codegen.lightapi.net with your OpenAPI specification and a config file.