loafle/openapi-generator
3
0
Fork 0
forked from loafle/openapi-generator-original
Code Pull Requests Activity

Revert "[doc] Update new-generator steps (new.sh) (#7334)" (#7335)

Browse Source 
This reverts commit 151752aa9d6be346e8750fe14ade592ab3178826.
This commit is contained in:
William Cheng 2020-09-03 14:21:26 +08:00 committed by GitHub
parent 151752aa9d
commit e0ec332e38
No known key found for this signature in database
GPG Key ID: 4AEE18F83AFDEB23
3 changed files with 117 additions and 40 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

77
docs/new-generator.md
View File

@ -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)
* Config file under `./bin/configs`
* Sample scripts under `./bin`
- 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,8 +43,6 @@ 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.
@ -57,7 +55,8 @@ 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/configs/kotlin-server-petstore-new.yaml
bin/windows/kotlin-server-petstore.bat
bin/kotlin-server-petstore.sh
Create a generic C# server generator:
./new.sh -n csharp -s -t
@ -66,7 +65,8 @@ 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/configs/csharp-server-petstore-new.yaml
bin/windows/csharp-server-petstore.bat
bin/csharp-server-petstore.sh
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,7 +88,8 @@ 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/configs/common-mark-documentation-petstore-new.yaml
Creating bin/windows/common-mark-documentation-petstore.bat
Creating bin/common-mark-documentation-petstore.sh
Finished.
```
@ -150,7 +151,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 = "Apis";
apiPackage = File.separator + "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.
@ -158,7 +159,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 = "Models";
modelPackage = File.separator + "Models";
```
Similarly, this sets the package for `Models`.
@ -329,29 +330,61 @@ To compile quickly to test this out, you can run `mvn clean package -DskipTests`
### Compile Sample
The `new.sh` script created the generation config file `bin/configs/common-mark-documentation-petstore-new.yaml`:
The `new.sh` script created `bin/common-mark-documentation-petstore.sh`:
```bash
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"
#!/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}
```
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.
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`).
Configuration based examples allow us to test the same samples in each tooling option (CLI, Gradle Plugin, Maven Plugin, etc.).
Add `-t modules/openapi-generator/src/main/resources/common-mark-documentation` to `ags` line to simplify the evaluation of template-only modifications:
You can compile your generator by running:
```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
```bash
./bin/generate-samples.sh bin/configs/common-mark-documentation-petstore-new.yaml
# 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}
```
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.

2
modules/openapi-generator/src/main/resources/META-INF/services/org.openapitools.codegen.CodegenConfig
View File

@ -127,5 +127,3 @@ org.openapitools.codegen.languages.TypeScriptJqueryClientCodegen
org.openapitools.codegen.languages.TypeScriptNodeClientCodegen
org.openapitools.codegen.languages.TypeScriptReduxQueryClientCodegen
org.openapitools.codegen.languages.TypeScriptRxjsClientCodegen
org.openapitools.codegen.languages.CommonMarkDocumentationCodegen

78
new.sh
View File

@ -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-zA-Z])\)/-\1/')
$(grep "[[:space:]].)\ #" $0 | tr -d "#" | sed -E 's/( \| \*)//' | sed -E 's/([a-z])\)/-\1/')
Examples:
Create a server generator for ktor:
@ -21,7 +21,8 @@ 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/configs/kotlin-server-petstore-new.yaml
bin/windows/kotlin-server-petstore.bat
bin/kotlin-server-petstore.sh
Create a generic C# server generator:
$0 -n csharp -s -t
@ -30,7 +31,8 @@ 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/configs/csharp-server-petstore-new.yaml
bin/windows/csharp-server-petstore.bat
bin/csharp-server-petstore.sh
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
@ -54,7 +56,7 @@ checkPreviousGenType() {
}
[ $# -eq 0 ] && usage
while getopts ":hcsdtfHn:" arg; do
while getopts ":hcsdtn:" arg; do
case ${arg} in
n) # Required. Specify generator name, should be kebab-cased.
gen_name=${OPTARG}
@ -71,7 +73,7 @@ while getopts ":hcsdtfHn:" arg; do
checkPreviousGenType
gen_type=documentation
;;
H) # Create a schema generator
h) # Create a schema generator
checkPreviousGenType
gen_type=schema
;;
@ -179,8 +181,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 = "Apis";
modelPackage = "Models";
apiPackage = File.separator + "Apis";
modelPackage = File.separator + "Models";
supportingFiles.add(new SupportingFile("README.mustache", "", "README.md"));
// TODO: Fill this out.
}
@ -199,17 +201,61 @@ 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 generation config scripts
echo "Creating bin/configs/${gen_name_camel}-${gen_type}-petstore-new.yaml"
cat > "${root}/bin/configs/${gen_name_camel}-${gen_type}-petstore-new.yaml"<<EOF
generatorName: ${gen_name_camel}
outputDir: samples/${gen_type}/petstore/${gen_name_camel_path}
inputSpec: modules/openapi-generator/src/test/resources/2_0/petstore.yaml
templateDir: modules/openapi-generator/src/main/resources/${gen_name_camel}
additionalProperties:
hideGenerationTimestamp: "true"
# 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"<<EOF
set executable=.\modules\openapi-generator-cli\target\openapi-generator-cli.jar
If Not Exist %executable% (
mvn clean package
)
REM set JAVA_OPTS=%JAVA_OPTS% -Xmx1024M -DloggerPath=conf/log4j.properties
set ags=generate --artifact-id "${gen_name_camel}-petstore-${gen_type}" -i modules\openapi-generator\src\test\resources\2_0\petstore.yaml -g ${gen_name_camel} -o samples\\${gen_type}\petstore\\${gen_name_camel_pathwin}
java %JAVA_OPTS% -jar %executable% %ags%
EOF
## Bash file
echo "Creating bin/${gen_name_camel}-${gen_type}-petstore.sh"
cat > "${root}/bin/${gen_name_camel}-${gen_type}-petstore.sh"<<EOF
#!/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 ${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}"