From 740395ea197d1b64dec41846ae8aec04bb176dad Mon Sep 17 00:00:00 2001 From: frantuma Date: Mon, 11 May 2020 22:17:41 +0200 Subject: [PATCH] docs: standalone generator development --- README.md | 7 ++- .../main/resources/codegen/myFile.template | 2 + standalone-gen-dev/docker-entrypoint.sh | 16 +++++ standalone-gen-dev/docker-stub.sh | 10 ++++ standalone-gen-dev/generator-stub-docker.sh | 11 ++++ standalone-gen-dev/run-in-docker.sh | 18 ++++++ .../standalone-generator-development.md | 58 +++++++++++++++++++ 7 files changed, 121 insertions(+), 1 deletion(-) create mode 100644 modules/swagger-codegen/src/main/resources/codegen/myFile.template create mode 100755 standalone-gen-dev/docker-entrypoint.sh create mode 100755 standalone-gen-dev/docker-stub.sh create mode 100755 standalone-gen-dev/generator-stub-docker.sh create mode 100755 standalone-gen-dev/run-in-docker.sh create mode 100644 standalone-gen-dev/standalone-generator-development.md diff --git a/README.md b/README.md index 8b373451c39..774d6f45359 100644 --- a/README.md +++ b/README.md @@ -204,7 +204,7 @@ To build from source, you need the following installed and available in your `$P * [Apache maven 3.3.3 or greater](http://maven.apache.org/) #### OS X Users -Don't forget to install Java 8+. +Don't forget to install Java 8+. Export `JAVA_HOME` in order to use the supported Java version: ```sh @@ -259,6 +259,9 @@ Once built, `run-in-docker.sh` will act as an executable for swagger-codegen-cli ./run-in-docker.sh generate -i modules/swagger-codegen/src/test/resources/2_0/petstore.yaml \ -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/master/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). @@ -458,6 +461,8 @@ 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/master/standalone-gen-dev/standalone-generator-development.md) + ### Where is Javascript??? See our [javascript library](http://github.com/swagger-api/swagger-js)--it's completely dynamic and doesn't require static code generation. diff --git a/modules/swagger-codegen/src/main/resources/codegen/myFile.template b/modules/swagger-codegen/src/main/resources/codegen/myFile.template new file mode 100644 index 00000000000..ac29967fb6e --- /dev/null +++ b/modules/swagger-codegen/src/main/resources/codegen/myFile.template @@ -0,0 +1,2 @@ + +# This is a sample supporting file mustache template. diff --git a/standalone-gen-dev/docker-entrypoint.sh b/standalone-gen-dev/docker-entrypoint.sh new file mode 100755 index 00000000000..d4a3d407e27 --- /dev/null +++ b/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}" +codegen2="${cli}/swagger-codegen-cli.jar" + +(cd "${GEN_DIR}" && exec mvn -Duser.home=$(dirname MAVEN_CONFIG) package) +command=$1 +shift +exec java ${JAVA_OPTS} -cp "${codegen2}:${GEN_DIR}/target/*" "io.swagger.codegen.SwaggerCodegen" "${command}" "$@" + diff --git a/standalone-gen-dev/docker-stub.sh b/standalone-gen-dev/docker-stub.sh new file mode 100755 index 00000000000..3a39a9419fb --- /dev/null +++ b/standalone-gen-dev/docker-stub.sh @@ -0,0 +1,10 @@ +#!/bin/sh +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"} + +codegen2="${GEN_DIR}/swagger-codegen-cli.jar" + +command=$1 +exec java ${JAVA_OPTS} -jar "${codegen2}" "meta" "$@" diff --git a/standalone-gen-dev/generator-stub-docker.sh b/standalone-gen-dev/generator-stub-docker.sh new file mode 100755 index 00000000000..1abd87117ba --- /dev/null +++ b/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 "$@" diff --git a/standalone-gen-dev/run-in-docker.sh b/standalone-gen-dev/run-in-docker.sh new file mode 100755 index 00000000000..31c47764503 --- /dev/null +++ b/standalone-gen-dev/run-in-docker.sh @@ -0,0 +1,18 @@ +#!/bin/bash +set -exo pipefail + +cd "$(dirname ${BASH_SOURCE})" + +maven_cache_repo="${HOME}/.m2/repository" + +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 "$@" diff --git a/standalone-gen-dev/standalone-generator-development.md b/standalone-gen-dev/standalone-generator-development.md new file mode 100644 index 00000000000..69e852d8c92 --- /dev/null +++ b/standalone-gen-dev/standalone-generator-development.md @@ -0,0 +1,58 @@ +### Swagger Codegen 2.x Standalone generator development (separate project/repo) + +As described in [Readme](https://github.com/swagger-api/swagger-codegen/tree/master#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/swagger-codegen-cli/2.4.13/swagger-codegen-cli-2.4.13.jar -O swagger-codegen-cli.jar +java -jar swagger-codegen-cli.jar meta -o output/myLibrary -n myClientCodegen -p com.my.company.codegen +``` + +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/master#making-your-own-codegen-modules). + + +#### Development in docker + +Similar to what mentioned in Readme [development in docker section](https://github.com/swagger-api/swagger-codegen/tree/master#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/swagger-codegen-cli/2.4.13/swagger-codegen-cli-2.4.13.jar -O swagger-codegen-cli.jar +wget https://raw.githubusercontent.com/swagger-api/swagger-codegen/master/standalone-gen-dev/docker-stub.sh -O docker-stub.sh +wget https://raw.githubusercontent.com/swagger-api/swagger-codegen/master/standalone-gen-dev/generator-stub-docker.sh -O generator-stub-docker.sh +chmod +x *.sh +# generated initial stub: -p -n +./generator-stub-docker.sh -p io.swagger.codegen.custom -n custom + +``` + +A test definition if we don't have one: + +```bash +wget https://raw.githubusercontent.com/swagger-api/swagger-codegen/master/modules/swagger-codegen/src/test/resources/2_0/petstore.yaml -O petstore.yaml +``` + + +Build the generator and run it against a definition (first time will be slower as it needs to download deps) + +```bash +wget https://raw.githubusercontent.com/swagger-api/swagger-codegen/master/standalone-gen-dev/run-in-docker.sh -O run-in-docker.sh +wget https://raw.githubusercontent.com/swagger-api/swagger-codegen/master/standalone-gen-dev/docker-entrypoint.sh -O docker-entrypoint.sh +chmod +x *.sh +./run-in-docker.sh generate -i petstore.yaml -l custom -o /gen/$GENERATED_CODE_DIR +``` + +