[DEPRECATED] This repository is now deprecated as it's functionality has been integrated into the main swagger-codegen project.
This is a Bash client script generator for REST services from their Swagger™ specification. The generated script provides a wrapper layer over cURL.
This generator uses swagger-codegen.
For more information about Swagger™ check out OpenAPI-Spec.
--dry-run
optionGet the sources:
$ git clone https://github.com/bkryza/bash-swagger-codegen
Build the codegen:
$ mvn assembly:assembly -DdescriptorId=jar-with-dependencies
Define custom codegen properties in a Json file, e.g.:
{
"processMarkdown": true,
"curlOptions": "-sS --tlsv1.2",
"scriptName": "petstore-cli",
"generateBashCompletion": true,
"generateZshCompletion": true,
"hostEnvironmentVariable": "PETSTORE_HOST",
"basicAuthEnvironmentVariable": "PETSTORE_BASIC_AUTH",
"apiKeyAuthEnvironmentVariable": "PETSTORE_API_KEY"
}
Generate the client:
$ java -cp target/bash-swagger-codegen-1.0.0.jar io.swagger.codegen.SwaggerCodegen generate -l bash -i http://petstore.swagger.io/v2/swagger.json -o output -c resources/example-config.json
$ chmod +x output/petstore-cli
Enjoy:
$ output/petstore-cli -h
Swagger Petstore command line client (API version 1.0.0)
Usage
petstore-cli [-h|--help] [-V|--version] [--about] [<curl-options>]
[-ac|--accept <mime-type>] [-ct,--content-type <mime-type>]
[--host <url>] [--dry-run] <operation> [-h|--help] [<headers>]
[<parameters>] [<body-parameters>]
- <url> - endpoint of the REST service without basepath
Can also be specified in PETSTORE_HOST environment variable.
- <curl-options> - any valid cURL options can be passed before <operation>
- <mime-type> - either full mime-type or one of supported abbreviations:
(text, html, md, csv, css, rtf, json, xml, yaml, js, bin,
rdf, jpg, png, gif, bmp, tiff)
- <headers> - HTTP headers can be passed in the form HEADER:VALUE
- <parameters> - REST operation parameters can be passed in the following
forms:
* KEY=VALUE - path or query parameters
- <body-parameters> - simple JSON body content (first level only) can be build
using the following arguments:
* KEY==VALUE - body parameters which will be added to body
JSON as '{ ..., "KEY": "VALUE", ... }'
* KEY:=VALUE - body parameters which will be added to body
JSON as '{ ..., "KEY": VALUE, ... }'
Authentication methods
- Api-key - add 'api_key:<api-key>' after <operation>
or export PETSTORE_API_KEY='<api-key>'
- OAuth2 (flow: implicit)
Authorization URL:
* http://petstore.swagger.io/oauth/dialog
Scopes:
* write:pets - modify pets in your account
* read:pets - read your pets
Operations (grouped by tags)
[pet]
addPet Add a new pet to the store
deletePet Deletes a pet
findPetsByStatus Finds Pets by status
findPetsByTags Finds Pets by tags
getPetById Find pet by ID
updatePet Update an existing pet
updatePetWithForm Updates a pet in the store with form data
uploadFile uploads an image
[store]
deleteOrder Delete purchase order by ID
getInventory Returns pet inventories by status
getOrderById Find purchase order by ID
placeOrder Place an order for a pet
[user]
createUser Create user
createUsersWithArrayInput Creates list of users with given input array
createUsersWithListInput Creates list of users with given input array
deleteUser Delete user
getUserByName Get user by user name
loginUser Logs user into the system
logoutUser Logs out current logged in user session
updateUser Updated user
Options
-h,--help Print this help
-V,--version Print API version
--about Print the information about service
--host <url> Specify the host URL
(e.g. 'https://petstore.swagger.io')
--force Force command invocation in spite of missing
required parameters or wrong content type
--dry-run Print out the cURL command without
executing it
-ac,--accept <mime-type> Set the 'Accept' header in the request
-ct,--content-type <mime-type> Set the 'Content-type' header in
the request
Client generator takes several specific configuration options:
true
, all text (descriptions) in the Swagger specification will be treated as Markdown and converted to terminal formatting commands,true
the Bash completion script will be generatedtrue
the Bash completion script will be generatedThese options can be specified in a Json file used when running the codegen using option -c
(see example).
# Print the list of operations available on the service
$ output/petstore-cli --help
# Print the service description
$ output/petstore-cli --about
# Print detailed information about specific operation
$ output/petstore-cli addPet --help
# Call REST API operation
$ echo '{"id":891,"name":"lucky","status":"available"}' | output/petstore-cli --host http://petstore.swagger.io --content-type json addPet
{"id":891,"name":"lucky","photoUrls":[],"tags":[],"status":"available"}
# The above is equivalent to
$ output/petstore-cli --host http://petstore.swagger.io --content-type json --accept xml addPet id:=891 name==lucky status==available
<xml version="1.0" encoding="UTF-8" standalone="yes"?><Pet><id>891</id><name>lucky</name><photoUrls/><status>available</status><tags/></Pet>
# Preview the cURL command without actually executing it
# The above is equivalent to
$ output/petstore-cli --host http://petstore.swagger.io --content-type json --dry-run addPet id:=891 name==lucky status==available
curl -sS --tlsv1.2 -H 'Content-type: application/json' -X POST -d '{"name": "lucky", "status": "available", "id": 891}' "http://petstore.swagger.io/v2/pet"
The generated bash-completion script can be either directly loaded to the current Bash session using:
source output/petstore-cli.bash-completion
Alternatively, the script can be copied to the /etc/bash-completion.d
(or on OSX with Homebrew to /usr/local/etc/bash-completion.d
):
sudo cp /output/petstore-cli.bash-completion /etc/bash-completion.d/petstore-cli
On OSX you might need to install bash-completion using Homebrew:
brew install bash-completion
and add the following to the ~/.bashrc
:
if [ -f $(brew --prefix)/etc/bash_completion ]; then
. $(brew --prefix)/etc/bash_completion
fi
In Zsh, the generated _{{scriptName}}
file (e.g. _petstore-cli) must be copied to one of the folders under $fpath
variable.
--help
and --about
formattingCopyright 2016 Bartosz Kryza bkryza@gmail.com
Licensed under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at
http://www.apache.org/licenses/LICENSE-2.0
Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.