search

bkryza / bash-swagger-codegen

Bash client code Swagger codegen
Apache License 2.0
6 stars 2 forks source link

readme

Bash client Swagger codegen

Build Status

[DEPRECATED] This repository is now deprecated as it's functionality has been integrated into the main swagger-codegen project.

Overview

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.

Features

Usage

Generating Bash client for REST service

Get 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:

These options can be specified in a Json file used when running the codegen using option -c (see example).

Using the generated Bash script

# 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"

Shell completion

Bash

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

OS X

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

Zsh

In Zsh, the generated _{{scriptName}} file (e.g. _petstore-cli) must be copied to one of the folders under $fpath variable.

TODO

LICENSE

Copyright 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.