Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

[Bash] Bash client script generator #4541

Merged
merged 6 commits into from
Jan 12, 2017

Conversation

bkryza
Copy link
Contributor

@bkryza bkryza commented Jan 12, 2017

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 wing328 added this to the v2.2.2 milestone Jan 12, 2017
@wing328
Copy link
Contributor

wing328 commented Jan 12, 2017

@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 wing328 merged commit 0fb154e into swagger-api:master Jan 12, 2017
@wing328
Copy link
Contributor

wing328 commented Jan 12, 2017

@bkryza
Copy link
Contributor Author

bkryza commented Jan 12, 2017

@wing328

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

@wing328
Copy link
Contributor

wing328 commented Jan 12, 2017

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

davidgri pushed a commit to davidgri/swagger-codegen that referenced this pull request May 11, 2017
* Initial commit

* Remormatted petstore tests

* Added Bash codegen to main README.md

* Added bash to integration tests

* Fixed stdin detection in generated script

* Added back ruby module
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Projects
None yet
Development

Successfully merging this pull request may close these issues.

2 participants