[Bash] Bash client script generator

[bkryza]

PR checklist

• Read the contribution guildelines.
• Ran the shell/batch script under ./bin/ to update Petstore sample so that CIs can verify the change. (For instance, only need to run ./bin/{LANG}-petstore.sh and ./bin/security/{LANG}-petstore.sh if updating the {LANG} (e.g. php, ruby, python, etc) code generator or {LANG} client's mustache templates)
• Filed the PR against the correct branch: master for non-breaking changes and 2.3.0 branch for breaking (non-backward compatible) changes.

Description of the PR

@wing328

This is a PR with a new template for generating standalone single-file Bash script clients whose only dependencies are Bash >4.3 and cURL.

The generated script contains a comprehensive help for listing all operations of the service as well as detailed help for each operation.

In addition, the codegen generates Bash and Zsh completion scripts which greatly simplifies usage of the script for larger API's.

Underneath, the script uses cURL to generate actual REST calls.

The main advantage of this generator is the possibility to create a command line tool which can be used to instantly test a web service without writing a single line of code, or to provide your web service users with a simple tool which they can download from a URL without the need to install any dependencies and development frameworks.

Main features

• Fully automatic generation of a working Bash script to access any Swagger-defined REST service
• Generation of Bash and Zsh completion scripts
• All valid cURL options can be passed directly
• Preview of cURL commands to execute each operation using --dry-run option
• Complete help for entire service as well as for each operation
• No external dependencies besides Bash >= 4.3 and cURL

Usage

If you'd like to check the generator in practice you can to this in these few steps after cloning the PR:

$ mvn package

$ java -jar modules/swagger-codegen-cli/target/swagger-codegen-cli.jar generate -i http://petstore.swagger.io/v2/swagger.json -l bash -o output/bash -c modules/swagger-codegen/src/test/resources/2_0/bash-config.json

$ chmod u+x output/bash/petstore-cli

# Get help on all service operations and authentication options
$ output/bash/petstore-cli -h

# Get detailed help on specific operation
$ output/bash/petstore-cli getUserByName -h

# Make a GET request
$ output/bash/petstore-cli --host http://petstore.swagger.io getUserByName username=wing

# Make a POST request by providing body content via pipe
$ echo '{"id":891,"name":"lucky","status":"available"}' | output/bash/petstore-cli --host http://petstore.swagger.io --content-type json addPet -

# make a POST request by creating a simple JSON using command line arguments
$ output/bash/petstore-cli --host http://petstore.swagger.io --content-type json addPet id:=891 name==lucky status==available

# Make a GET request with specific accept mime type
$ output/bash/petstore-cli --host http://petstore.swagger.io --accept xml getPetById petId=891

More information is available in the README.md in codegen resources here.

Tests

I added basic unit tests for the Java part of the generator as well as integration tests for the petstore service.

For the integration tests I needed 2 dependencies to the main .travis.yml

• Bats a Bash test framework
• [cURL] to make sure the generated script can make the REST calls

Please let me know what you think about this codegen and how can I improve it to integrate it into master.

[wing328]

@bkryza this PR is of very high quality 🍻 . Thanks for your contribution 👍

One suggestion I have is to check the Bash version at the start. Here is what I got when running with Bash 3.x:

output/bash/petstore-cli: line 133: getOrderById:::orderId: syntax error in expression (error token is ":::orderId")
output/bash/petstore-cli: line 134: placeOrder:::body: syntax error in expression (error token is ":::body")
output/bash/petstore-cli: line 135: createUser:::body: syntax error in expression (error token is ":::body")
output/bash/petstore-cli: line 136: createUsersWithArrayInput:::body: syntax error in expression (error token is ":::body")
output/bash/petstore-cli: line 137: createUsersWithListInput:::body: syntax error in expression (error token is ":::body")
output/bash/petstore-cli: line 138: deleteUser:::username: syntax error in expression (error token is ":::username")
output/bash/petstore-cli: line 139: getUserByName:::username: syntax error in expression (error token is ":::username")
output/bash/petstore-cli: line 140: loginUser:::username: syntax error in expression (error token is ":::username")
output/bash/petstore-cli: line 141: loginUser:::password: syntax error in expression (error token is ":::password")
output/bash/petstore-cli: line 142: updateUser:::username: syntax error in expression (error token is ":::username")
output/bash/petstore-cli: line 143: updateUser:::body: syntax error in expression (error token is ":::body")
output/bash/petstore-cli: line 150: declare: -A: invalid option
declare: usage: declare [-afFirtx] [-p] [name[=value] ...]
output/bash/petstore-cli: line 198: declare: -A: invalid option
declare: usage: declare [-afFirtx] [-p] [name[=value] ...]
Sorry - your Bash version is 3.2.57(1)-release

You need at least Bash 4.3 to run this script.

It's showing the error message about incorrect Bash version at the end. What I would suggest is to perform a check at the start so as to avoid showing too many syntax error messages (as some users might simply skip all the error messages when the result is showing too many errors...)

[wing328]

Tweet: https://twitter.com/wing328/status/819467329528438784

[bkryza]

@wing328

Thanks for the merge. I created an issue for the version check #4543 - I will try to fix it.

[wing328]

@bkryza thanks! It's not really an issue, just a minor enhancement to make it better 😄