diff --git a/README.md b/README.md index c9062993c90..3b232f224c7 100644 --- a/README.md +++ b/README.md @@ -167,6 +167,49 @@ export JAVA_HOME=`/usr/libexec/java_home -v 1.8` export PATH=${JAVA_HOME}/bin:$PATH ``` +### Launcher Script + +One downside to manual jar downloads is that you don't keep up-to-date with the latest released version. We have a Bash launcher script at [bin/utils/openapi-generator.cli.sh](./bin/utils/openapi-generator.cli.sh) which resolves this issue. + +To install the launcher script, copy the contents of the script to a location on your path and make the script executable. + +An example of setting this up (NOTE: Always evaluate scripts curled from external systems before executing them). + +``` +mkdir -p ~/bin/openapitools +curl https://raw.githubusercontent.com/OpenAPITools/openapi-generator/master/bin/utils/openapi-generator.cli.sh > ~/bin/openapitools/openapi-generator-cli +chmod u+x ~/bin/openapitools/openapi-generator-cli +export PATH=$PATH:~/bin/openapitools/ +``` + +Now, `openapi-generator-cli` is "installed". On invocation, it will query the GitHub repository for the most recently released version. If this matches the last downloaded jar, +it will execute as normal. If a newer version is found, the script will download the latest release and execute it. + +If you need to invoke an older version of the generator, you can define the variable `OPENAPI_GENERATOR_VERSION` either ad hoc or globally. You can export this variable if you'd like to persist a specific release version. + +Examples: + +``` +# Execute latest released openapi-generator-cli +openapi-generator-cli version + +# Execute version 3.1.0 for the current invocation, regardless of the latest released version +OPENAPI_GENERATOR_VERSION=3.1.0 openapi-generator-cli version + +# Execute version 3.1.0-SNAPSHOT for the current invocation +OPENAPI_GENERATOR_VERSION=3.1.0-SNAPSHOT openapi-generator-cli version + +# Execute version 3.0.2 for every invocation in the current shell session +export OPENAPI_GENERATOR_VERSION=3.0.2 +openapi-generator-cli version # is 3.0.2 +openapi-generator-cli version # is also 3.0.2 + +# To "install" a specific version, set the variable in .bashrc/.bash_profile +echo "export OPENAPI_GENERATOR_VERSION=3.0.2" >> ~/.bashrc +source ~/.bashrc +openapi-generator-cli version # is always 3.0.2, unless any of the above overrides are done ad hoc +``` + ### [1.4 - Build Projects](#table-of-contents) To build from source, you need the following installed and available in your `$PATH:` diff --git a/bin/utils/openapi-generator-cli.sh b/bin/utils/openapi-generator-cli.sh new file mode 100644 index 00000000000..0f1016f9aed --- /dev/null +++ b/bin/utils/openapi-generator-cli.sh @@ -0,0 +1,60 @@ +#!/usr/bin/env bash +#### +# Save as openapi-generator-cli on your PATH. chmod u+x. Enjoy. +# +# This script will query github on every invocation to pull the latest released version +# of openapi-generator. +# +# If you want repeatable executions, you can explicitly set a version via +# OPENAPI_GENERATOR_VERSION +# e.g. (in Bash) +# export OPENAPI_GENERATOR_VERSION=3.1.0 +# openapi-generator-cli.sh +# or +# OPENAPI_GENERATOR_VERSION=3.1.0 openapi-generator-cli.sh +# +# This is also helpful, for example, if you want want to evaluate a SNAPSHOT version. +# +# NOTE: Jars are downloaded on demand from maven into the same directory as this script +# for every 'latest' version pulled from github. Consider putting this under its own directory. +#### +set -o pipefail + +for cmd in {mvn,python,curl}; do + if ! command -v ${cmd} > /dev/null; then + >&2 echo "This script requires '${cmd}' to be installed." + exit 1 + fi +done + +function latest.tag { + local uri="https://api.github.com/repos/${1}/tags" + curl -s ${uri} | python -c "import sys, json; print json.load(sys.stdin)[0]['name'][1:]" +} + +ghrepo=openapitools/openapi-generator +groupid=org.openapitools +artifactid=openapi-generator-cli +ver=${OPENAPI_GENERATOR_VERSION:-$(latest.tag $ghrepo)} + +jar=${artifactid}-${ver}.jar +DIR="$( cd "$( dirname "${BASH_SOURCE[0]}" )" && pwd )" + +if [ ! -f ${DIR}/${jar} ]; then + repo="central::default::https://repo1.maven.apache.org/maven2" + if [[ ${ver} =~ ^.*-SNAPSHOT$ ]]; then + repo="central::default::https://oss.sonatype.org/content/repositories/snapshots" + fi + mvn org.apache.maven.plugins:maven-dependency-plugin:2.9:get \ + -DremoteRepositories=${repo} \ + -Dartifact=${groupid}:${artifactid}:${ver} \ + -Dtransitive=false \ + -Ddest=${DIR}/${jar} +fi + +java -ea \ + ${JAVA_OPTS} \ + -Xms512M \ + -Xmx1024M \ + -server \ + -jar ${DIR}/${jar} "$@" \ No newline at end of file diff --git a/scripts/openapi-generator-cli-completion.bash b/scripts/openapi-generator-cli-completion.bash new file mode 100644 index 00000000000..96233fb22ed --- /dev/null +++ b/scripts/openapi-generator-cli-completion.bash @@ -0,0 +1,46 @@ +#!/usr/bin/env bash + +### +# Provides completion assistance for openapi-generator-cli +# Install +# Mac: +# brew install bash-completion +# cp openapi-generator-cli-completion.bash `brew --prefix`/etc/bash_completion.d +# Linux: many distributions include this automatically. Search for your distro-specific instructions. +# When in doubt, try sourcing this file: +# type complete && source openapi-generator-cli +# +# see http://tldp.org/LDP/abs/html/tabexpansion.html +### + +_openapi_generator_cli_completions() { + COMPREPLY=() + local IFS=$' \t\n' + local options=() + + options+=("$($1 completion ${COMP_WORDS[@]:1})") + + case "${COMP_WORDS[1]}" in + generate) + case "${COMP_WORDS[@]:2}" in + -l|--lang|-g|--generator-name) + # TODO: This is a nice-to-have and not required. + # Apply generator-specific options to additional properties. These can be queried via: + # openapi-generator-cli config-help -l YOUR_LANG | grep '^\t' | grep -v '^\t\s\s\s\s' | tr -d '\t' + # where YOUR_LANG would need to be evaluated as the value after the current switch. + # but rather than switching on 'generate' maybe switch on --additional-properties? + ;; + esac + ;; + *) + # ignore + ;; + esac + + # printf '%s\n' "${options[@]}" + if [[ -n "${options[@]}" ]]; then + COMPREPLY=( $(compgen -W "${options}" -- ${2}) ) + fi +} + +complete -F _openapi_generator_cli_completions openapi-generator-cli