From 03f95f0f48bd654c8a232db5a20d0dc24b8ffb64 Mon Sep 17 00:00:00 2001
From: Jim Schubert <james.schubert@gmail.com>
Date: Fri, 11 Sep 2020 21:40:42 -0400
Subject: [PATCH] [docs] Add notes on Windows classpath modification

---
 docs/customization.md | 11 ++++++++---
 docs/templating.md    |  8 ++++++--
 2 files changed, 14 insertions(+), 5 deletions(-)

diff --git a/docs/customization.md b/docs/customization.md
index 8d3ec378a30..8bf21c7dbae 100644
--- a/docs/customization.md
+++ b/docs/customization.md
@@ -20,7 +20,12 @@ These names can be anything you like. If you are building a client for the white
 
 ### Use your new generator with the CLI
 
-To compile your library, enter the `out/generators/my-codegen` directory, run `mvn package` and execute the generator:
+To compile your library, enter the `out/generators/my-codegen` directory, run `mvn package`.
+
+**NOTE** Running your custom generator requires adding it to the classpath. This differs on [Windows](https://docs.oracle.com/javase/8/docs/technotes/tools/windows/classpath.html) slightly from [unix](https://docs.oracle.com/javase/8/docs/technotes/tools/unix/classpath.html).
+If you are running a Windows Subsystem for Linux or a shell such as gitbash, and have issues with the unix variant, try the Windows syntax below.
+ 
+Now, execute the generator:
 
 ```sh
 java -cp out/generators/my-codegen/target/my-codegen-openapi-generator-1.0.0.jar:modules/openapi-generator-cli/target/openapi-generator-cli.jar org.openapitools.codegen.OpenAPIGenerator
@@ -28,7 +33,7 @@ java -cp out/generators/my-codegen/target/my-codegen-openapi-generator-1.0.0.jar
 
 For Windows users, you will need to use `;` instead of `:` in the classpath, e.g.
 ```
-java -cp out/generators/my-codegen/target/my-codegen-openapi-generator-1.0.0.jar;modules/openapi-generator-cli/target/openapi-generator-cli.jar org.openapitools.codegen.OpenAPIGenerator
+java -cp "out/generators/my-codegen/target/my-codegen-openapi-generator-1.0.0.jar;modules/openapi-generator-cli/target/openapi-generator-cli.jar" org.openapitools.codegen.OpenAPIGenerator
 ```
 
 Note the `my-codegen` is an option for `-g` now, and you can use the usual arguments for generating your code:
@@ -42,7 +47,7 @@ java -cp out/codegens/customCodegen/target/my-codegen-openapi-generator-1.0.0.ja
 
 For Windows users:
 ```
-java -cp out/codegens/customCodegen/target/my-codegen-openapi-generator-1.0.0.jar;modules/openapi-generator-cli/target/openapi-generator-cli.jar \
+java -cp "out/codegens/customCodegen/target/my-codegen-openapi-generator-1.0.0.jar;modules/openapi-generator-cli/target/openapi-generator-cli.jar" \
   org.openapitools.codegen.OpenAPIGenerator generate -g my-codegen \
   -i https://raw.githubusercontent.com/openapitools/openapi-generator/master/modules/openapi-generator/src/test/resources/2_0/petstore.yaml \
   -o ./out/myClient
diff --git a/docs/templating.md b/docs/templating.md
index 19c80f632df..83444857acf 100644
--- a/docs/templating.md
+++ b/docs/templating.md
@@ -48,7 +48,9 @@ java -cp /path/totemplate-classpath-example-1.0-SNAPSHOT.jar:modules/openapi-gen
     -g html -o template-example -t templates/htmlDocs
 ```
 
-Note that our template directory is relative to the resource directory of the JAR defined on the classpath.
+**NOTE** Running your custom generator in the example above requires adding it to the classpath. This differs on [Windows](https://docs.oracle.com/javase/8/docs/technotes/tools/windows/classpath.html) slightly from [unix](https://docs.oracle.com/javase/8/docs/technotes/tools/unix/classpath.html).
+
+Take note that our template directory is relative to the resource directory of the JAR defined on the classpath.
 
 ### Retrieving Templates
 
@@ -470,7 +472,9 @@ java $JAVA_OPTS -cp /your/path/build/libs/pebble-template-adapter-1.0-SNAPSHOT-a
     --global-property models,modelDocs,modelTests,apis,apiTests,apiDocs
 ```
 
-Notice how we've targeted our custom template engine adapter via `-e pebble`. If you don't include the SPI file under `META-INF/services`, you'll need to specify the exact classpath: `org.openapitools.examples.templating.PebbleTemplateAdapter`. Notice that the target class here matches the Kotlin class name. This is because of the `@file:JvmName` annotation.
+**NOTE** Running your custom generator requires adding it to the classpath. This differs on [Windows](https://docs.oracle.com/javase/8/docs/technotes/tools/windows/classpath.html) slightly from [unix](https://docs.oracle.com/javase/8/docs/technotes/tools/unix/classpath.html).
+
+In the above example, we've targeted our custom template engine adapter via `-e pebble`. If you don't include the SPI file under `META-INF/services`, you'll need to specify the exact classpath: `org.openapitools.examples.templating.PebbleTemplateAdapter`. Notice that the target class here matches the Kotlin class name. This is because of the `@file:JvmName` annotation.
 
 Congratulations on creating a custom templating engine adapter!
 
-- 
GitLab