From 1f50207bdaebd366393bda76a6c55261dd5f6730 Mon Sep 17 00:00:00 2001 From: William Cheng Date: Thu, 3 Sep 2020 22:04:43 +0800 Subject: [PATCH] [doc] Update new-generator steps (new.sh) (#7336) * [doc] Update new-generator steps (new.sh) (#7334) * remove CommonMarkDocumentationCodegen Co-authored-by: Jim Schubert --- docs/new-generator.md | 77 ++++++++++++------------------------------ new.sh | 78 +++++++++---------------------------------- 2 files changed, 38 insertions(+), 117 deletions(-) diff --git a/docs/new-generator.md b/docs/new-generator.md index 1526e91dff46..d440d2a7fd9d 100644 --- a/docs/new-generator.md +++ b/docs/new-generator.md @@ -23,7 +23,7 @@ The minimum set of files required to create a new generator are: - Should include a README explaining usage - Must include an `api.mustache` - Exists under `modules/openapi-generator/src/main/resources/` (plus `embeddedTemplate` dir value, see below) -* Sample scripts under `./bin` +* Config file under `./bin/configs` - Gives users a "real life" example of generated output - Samples are used by CI to verify generators and test for regressions in some cases @@ -43,6 +43,8 @@ Usage: -c Create a client generator -s Create a server generator -d Create a documentation generator + -H Create a schema generator + -f Create a config generator -t When specified, creates test file(s) for the generator. -h Display help. @@ -55,8 +57,7 @@ Examples: modules/openapi-generator/src/main/resources/kotlin-server/README.mustache modules/openapi-generator/src/main/resources/kotlin-server/model.mustache modules/openapi-generator/src/main/resources/kotlin-server/api.mustache - bin/windows/kotlin-server-petstore.bat - bin/kotlin-server-petstore.sh + bin/configs/kotlin-server-petstore-new.yaml Create a generic C# server generator: ./new.sh -n csharp -s -t @@ -65,8 +66,7 @@ Examples: modules/openapi-generator/src/main/resources/csharp-server/README.mustache modules/openapi-generator/src/main/resources/csharp-server/model.mustache modules/openapi-generator/src/main/resources/csharp-server/api.mustache - bin/windows/csharp-server-petstore.bat - bin/csharp-server-petstore.sh + bin/configs/csharp-server-petstore-new.yaml modules/openapi-generator/src/test/java/org/openapitools/codegen/csharp/CsharpServerCodegenTest.java modules/openapi-generator/src/test/java/org/openapitools/codegen/csharp/CsharpServerCodegenModelTest.java modules/openapi-generator/src/test/java/org/openapitools/codegen/csharp/CsharpServerCodegenOptionsTest.java @@ -88,8 +88,7 @@ Creating modules/openapi-generator/src/main/java/org/openapitools/codegen/langua Creating modules/openapi-generator/src/main/resources/common-mark-documentation/README.mustache Creating modules/openapi-generator/src/main/resources/common-mark-documentation/model.mustache Creating modules/openapi-generator/src/main/resources/common-mark-documentation/api.mustache -Creating bin/windows/common-mark-documentation-petstore.bat -Creating bin/common-mark-documentation-petstore.sh +Creating bin/configs/common-mark-documentation-petstore-new.yaml Finished. ``` @@ -151,7 +150,7 @@ The `templateDir` variable refers to the "current" template directory setting, a Both of these variables exist because the generator will fallback to files under `embeddedTemplateDir` if they are not defined in the user's custom template directory. ```java -apiPackage = File.separator + "Apis"; +apiPackage = "Apis"; ``` This sets the "package" location for anything considered an API document. You might want to change this setting if, for instance, your language doesn't support uppercase letters in the path. We don't need to worry about that here. @@ -159,7 +158,7 @@ This sets the "package" location for anything considered an API document. You mi Every templated output from `api.mustache` (registered via `apiTemplateFiles` above) will end up in the directory defined by `apiPackage` here. ```java -modelPackage = File.separator + "Models"; +modelPackage = "Models"; ``` Similarly, this sets the package for `Models`. @@ -330,61 +329,29 @@ To compile quickly to test this out, you can run `mvn clean package -DskipTests` ### Compile Sample -The `new.sh` script created `bin/common-mark-documentation-petstore.sh`: +The `new.sh` script created the generation config file `bin/configs/common-mark-documentation-petstore-new.yaml`: ```bash -#!/bin/sh - -SCRIPT="$0" - -while [ -h "$SCRIPT" ] ; do - ls=$(ls -ld "$SCRIPT") - link=$(expr "$ls" : '.*-> \(.*\)$') - if expr "$link" : '/.*' > /dev/null; then - SCRIPT="$link" - else - SCRIPT=$(dirname "$SCRIPT")/"$link" - fi -done - -if [ ! -d "${APP_DIR}" ]; then - APP_DIR=$(dirname "$SCRIPT")/.. - APP_DIR=$(cd "${APP_DIR}"; pwd) -fi - -executable="./modules/openapi-generator-cli/target/openapi-generator-cli.jar" - -if [ ! -f "$executable" ] -then - mvn clean package -fi - -# if you've executed sbt assembly previously it will use that instead. -export JAVA_OPTS="${JAVA_OPTS} -Xmx1024M -DloggerPath=conf/log4j.properties" -ags="$@ generate -i modules/openapi-generator/src/test/resources/2_0/petstore.yaml -g common-mark -o samples/documentation/petstore/common/mark" - -java ${JAVA_OPTS} -jar ${executable} ${ags} +generatorName: common-mark +outputDir: samples/documentation/petstore/common/mark +inputSpec: modules/openapi-generator/src/test/resources/2_0/petstore.yaml +templateDir: modules/openapi-generator/src/main/resources/common-mark +additionalProperties: + hideGenerationTimestamp: "true" ``` -This script is often used to apply default options for generation. A common option in most of these script is to define the template directory as the generator's directory under `resources`. This allows template maintainers to modify and test out template changes which don't require recompilation of the entire project. You'd still need to recompile the project in full if you add or modify behaviors to the generator (such as adding a `CliOption`). +This configuration file is passed to the generator's CLI tool during continuous integration builds, and many outputs are compiled and tested as a regression test on every build. Contributors are also asked to run `./bin/utils/ensure-up-to-date` before opening a pull request to regenerate all samples defined under `./bin/configs`. This allows maintainers to quickly verify whether changes impact other generators. -Add `-t modules/openapi-generator/src/main/resources/common-mark-documentation` to `ags` line to simplify the evaluation of template-only modifications: +Configuration based examples allow us to test the same samples in each tooling option (CLI, Gradle Plugin, Maven Plugin, etc.). -```diff -diff --git a/bin/markdown-documentation-petstore.sh b/bin/markdown-documentation-petstore.sh -index d816771478..94b4ce6d12 100644 ---- a/bin/markdown-documentation-petstore.sh -+++ b/bin/markdown-documentation-petstore.sh -@@ -26,6 +26,6 @@ fi +You can compile your generator by running: - # if you've executed sbt assembly previously it will use that instead. - export JAVA_OPTS="${JAVA_OPTS} -Xmx1024M -DloggerPath=conf/log4j.properties" --ags="$@ generate -i modules/openapi-generator/src/test/resources/2_0/petstore.yaml -g common-mark -o samples/documentation/petstore/common-mark" -+ags="$@ generate -t modules/openapi-generator/src/main/resources/common-mark-documentation -i modules/openapi-generator/src/test/resources/2_0/petstore.yaml -g common-mark -o samples/documentation/petstore/common/markdown" - - java ${JAVA_OPTS} -jar ${executable} ${ags} +```bash +./bin/generate-samples.sh bin/configs/common-mark-documentation-petstore-new.yaml ``` +This configuration file can be used to demonstrate the default options for generation. A common option in most of these configs is to define the template directory as the generator's directory under `resources`. This allows template maintainers to modify and test out template changes which don't require recompilation of the entire project. You'd still need to recompile the project in full if you add or modify behaviors to the generator (such as adding a `CliOption`). + ### Verify output Creating a new generator will be an iterative task. Once you've generated the sample, you'll want to try it out. For compiled client/server outputs, this would mean running the code or creating a small sample project to consume your artifact just to make sure it works. diff --git a/new.sh b/new.sh index c3dd7f499bf0..76bebf9a43c7 100755 --- a/new.sh +++ b/new.sh @@ -10,7 +10,7 @@ Stubs out files for new generators Usage: $0 [options] Options: -$(grep "[[:space:]].)\ #" $0 | tr -d "#" | sed -E 's/( \| \*)//' | sed -E 's/([a-z])\)/-\1/') +$(grep "[[:space:]].)\ #" $0 | tr -d "#" | sed -E 's/( \| \*)//' | sed -E 's/([a-zA-Z])\)/-\1/') Examples: Create a server generator for ktor: @@ -21,8 +21,7 @@ Examples: modules/openapi-generator/src/main/resources/kotlin-server/README.mustache modules/openapi-generator/src/main/resources/kotlin-server/model.mustache modules/openapi-generator/src/main/resources/kotlin-server/api.mustache - bin/windows/kotlin-server-petstore.bat - bin/kotlin-server-petstore.sh + bin/configs/kotlin-server-petstore-new.yaml Create a generic C# server generator: $0 -n csharp -s -t @@ -31,8 +30,7 @@ Examples: modules/openapi-generator/src/main/resources/csharp-server/README.mustache modules/openapi-generator/src/main/resources/csharp-server/model.mustache modules/openapi-generator/src/main/resources/csharp-server/api.mustache - bin/windows/csharp-server-petstore.bat - bin/csharp-server-petstore.sh + bin/configs/csharp-server-petstore-new.yaml modules/openapi-generator/src/test/java/org/openapitools/codegen/csharp/CsharpServerCodegenTest.java modules/openapi-generator/src/test/java/org/openapitools/codegen/csharp/CsharpServerCodegenModelTest.java modules/openapi-generator/src/test/java/org/openapitools/codegen/csharp/CsharpServerCodegenOptionsTest.java @@ -56,7 +54,7 @@ checkPreviousGenType() { } [ $# -eq 0 ] && usage -while getopts ":hcsdtn:" arg; do +while getopts ":hcsdtfHn:" arg; do case ${arg} in n) # Required. Specify generator name, should be kebab-cased. gen_name=${OPTARG} @@ -73,7 +71,7 @@ while getopts ":hcsdtn:" arg; do checkPreviousGenType gen_type=documentation ;; - h) # Create a schema generator + H) # Create a schema generator checkPreviousGenType gen_type=schema ;; @@ -181,8 +179,8 @@ public class ${lang_classname} extends DefaultCodegen implements CodegenConfig { modelTemplateFiles.put("model.mustache", ".zz"); apiTemplateFiles.put("api.mustache", ".zz"); embeddedTemplateDir = templateDir = "${gen_name_camel}-${gen_type}"; - apiPackage = File.separator + "Apis"; - modelPackage = File.separator + "Models"; + apiPackage = "Apis"; + modelPackage = "Models"; supportingFiles.add(new SupportingFile("README.mustache", "", "README.md")); // TODO: Fill this out. } @@ -201,61 +199,17 @@ echo "Creating modules/openapi-generator/src/main/resources/${gen_name_camel}-${ echo "Creating modules/openapi-generator/src/main/resources/${gen_name_camel}-${gen_type}/api.mustache" && \ touch "${root}/modules/openapi-generator/src/main/resources/${gen_name_camel}-${gen_type}/api.mustache" -# Step 4: Create bash/batch scripts - -## Windows batch file -echo "Creating bin/windows/${gen_name_camel}-${gen_type}-petstore.bat" -cat > "${root}/bin/windows/${gen_name_camel}-${gen_type}-petstore.bat"< "${root}/bin/configs/${gen_name_camel}-${gen_type}-petstore-new.yaml"< "${root}/bin/${gen_name_camel}-${gen_type}-petstore.sh"< \(.*\)$') - if expr "\$link" : '/.*' > /dev/null; then - SCRIPT="\$link" - else - SCRIPT=\$(dirname "\$SCRIPT")/"\$link" - fi -done - -if [ ! -d "\${APP_DIR}" ]; then - APP_DIR=\$(dirname "\$SCRIPT")/.. - APP_DIR=\$(cd "\${APP_DIR}"; pwd) -fi - -executable="./modules/openapi-generator-cli/target/openapi-generator-cli.jar" - -if [ ! -f "\$executable" ] -then - mvn clean package -fi - -# if you've executed sbt assembly previously it will use that instead. -export JAVA_OPTS="\${JAVA_OPTS} -Xmx1024M -DloggerPath=conf/log4j.properties" -ags="\$@ generate -i modules/openapi-generator/src/test/resources/2_0/petstore.yaml -g ${gen_name_camel} -o samples/${gen_type}/petstore/${gen_name_camel_path}" - -java \${JAVA_OPTS} -jar \${executable} \${ags} -EOF - -chmod u+x "${root}/bin/${gen_name_camel}-${gen_type}-petstore.sh" - # Step 5: (optional) Create OpenAPI Generator test files if [ "1" -eq "${tests}" ]; then mkdir -p "${root}/modules/openapi-generator/src/test/java/org/openapitools/codegen/${gen_name_camel_path}"