From 3989314f6077f9fd78f02fafc307855c774e970d Mon Sep 17 00:00:00 2001 From: Eguzki Astiz Lezaun Date: Tue, 23 Oct 2018 12:24:23 +0200 Subject: [PATCH 1/8] README: documentation about update service command --- README.md | 41 +++++++++++++++++++++++++++++++++++++++++ 1 file changed, 41 insertions(+) diff --git a/README.md b/README.md index e624738c..0adfb593 100644 --- a/README.md +++ b/README.md @@ -23,6 +23,47 @@ Will create a new service, copy existing methods, metrics, application plans and 3scale copy service NUMBER --source=https://provider_key@foo-admin.3scale.net --destination=https://provider_key@foo2-admin.3scale.net ``` +### Update a service + +Will update existing service, update proxy settings, metrics, methods, application plans and mapping rules. + +Help docstring + +```shell +NAME + service - Update service + +USAGE + 3scale update service [opts] -s -d + + +DESCRIPTION + Will update existing service, update proxy settings, metrics, methods, + application plans and mapping rules. + +OPTIONS + -d --destination= 3scale target instance. Format: + "http[s]://@3scale_url" + -f --force Overwrites the mapping rules by deleting + all rules from target service first + -h --help show help for this command + -r --rules-only Updates only the mapping rules + -s --source= 3scale source instance. Format: + "http[s]://@3scale_url" + +OPTIONS FOR UPDATE + -h --help show help for this command + -k --insecure Proceed and operate even for server + connections otherwise considered insecure + -v --version Prints the version of this command +``` + +Example: + +```shell +$ 3scale update service -s https://234239874598743@3scaleinstance_source.com -d https://2342342342342@3scaleinstance_destination.com 3 2 +``` + ### Import from CSV Will create a new services, metrics, methods and mapping rules. From 12d56affd76e95da697699b4d278789dbbdc2026 Mon Sep 17 00:00:00 2001 From: Eguzki Astiz Lezaun Date: Tue, 23 Oct 2018 12:24:48 +0200 Subject: [PATCH 2/8] update_command/update_service: documentation about update service command --- .../commands/update_command/update_service.rb | 11 +++++------ 1 file changed, 5 insertions(+), 6 deletions(-) diff --git a/lib/3scale_toolbox/commands/update_command/update_service.rb b/lib/3scale_toolbox/commands/update_command/update_service.rb index ec722409..4cb6af02 100644 --- a/lib/3scale_toolbox/commands/update_command/update_service.rb +++ b/lib/3scale_toolbox/commands/update_command/update_service.rb @@ -9,19 +9,18 @@ module UpdateServiceSubcommand def self.command Cri::Command.define do name 'service' - usage 'service [options] ' - summary '3scale CLI update service' - description '3scale CLI update service tool' + usage 'service [opts] -s -d ' + summary 'Update service' + description 'Will update existing service, update proxy settings, metrics, methods, application plans and mapping rules.' flag :h, :help, 'show help for this command' do |_, cmd| puts cmd.help exit 0 end - required :s, :source, 'Source' - required :d, :destination, 'Destination' + required :s, :source, '3scale source instance. Format: "http[s]://@3scale_url"' + required :d, :destination, '3scale target instance. Format: "http[s]://@3scale_url"' flag :f, :force, 'Overwrites the mapping rules by deleting all rules from target service first' - # TODO: parametrize what parts of service need to be copied flag :r, 'rules-only', 'Updates only the mapping rules' run do |opts, args, _| From 47cad7a7228832a441750daaeaec9a3297eaf0dc Mon Sep 17 00:00:00 2001 From: Eguzki Astiz Lezaun Date: Tue, 23 Oct 2018 14:07:25 +0200 Subject: [PATCH 3/8] improve documentation of commands --- lib/3scale_toolbox/commands/copy_command.rb | 4 ++-- .../commands/copy_command/copy_service.rb | 10 +++++----- lib/3scale_toolbox/commands/import_command.rb | 4 ++-- .../commands/import_command/import_csv.rb | 10 +++++----- lib/3scale_toolbox/commands/update_command.rb | 4 ++-- 5 files changed, 16 insertions(+), 16 deletions(-) diff --git a/lib/3scale_toolbox/commands/copy_command.rb b/lib/3scale_toolbox/commands/copy_command.rb index da0836e6..9d8f0c0d 100644 --- a/lib/3scale_toolbox/commands/copy_command.rb +++ b/lib/3scale_toolbox/commands/copy_command.rb @@ -10,8 +10,8 @@ def self.command Cri::Command.define do name 'copy' usage 'copy [options]' - summary '3scale CLI copy' - description '3scale CLI copy tools to manage your API from the terminal.' + summary '3scale copy super command' + description '3scale copy super command.' flag :h, :help, 'show help for this command' do |_, cmd| puts cmd.help exit 0 diff --git a/lib/3scale_toolbox/commands/copy_command/copy_service.rb b/lib/3scale_toolbox/commands/copy_command/copy_service.rb index ed334dc9..873b5d8f 100644 --- a/lib/3scale_toolbox/commands/copy_command/copy_service.rb +++ b/lib/3scale_toolbox/commands/copy_command/copy_service.rb @@ -9,17 +9,17 @@ module CopyServiceSubcommand def self.command Cri::Command.define do name 'service' - usage 'service [options] ' - summary '3scale CLI copy service' - description '3scale CLI copy service tool' + usage 'service [opts] -s -d ' + summary 'Copy service' + description 'Will create a new services, copy existing proxy settings, metrics, methods, application plans and mapping rules.' flag :h, :help, 'show help for this command' do |_, cmd| puts cmd.help exit 0 end - required :s, :source, 'Source' - required :d, :destination, 'Destination' + required :s, :source, '3scale source instance. Format: "http[s]://@3scale_url"' + required :d, :destination, '3scale target instance. Format: "http[s]://@3scale_url"' required :t, 'target_system_name', 'Target system name' run do |opts, args, _| diff --git a/lib/3scale_toolbox/commands/import_command.rb b/lib/3scale_toolbox/commands/import_command.rb index 854b82da..35286b19 100644 --- a/lib/3scale_toolbox/commands/import_command.rb +++ b/lib/3scale_toolbox/commands/import_command.rb @@ -10,8 +10,8 @@ def self.command Cri::Command.define do name 'import' usage 'import [options]' - summary '3scale CLI import' - description '3scale CLI import tools to manage your API from the terminal.' + summary '3scale import super command' + description '3scale import super command.' flag :h, :help, 'show help for this command' do |_, cmd| puts cmd.help diff --git a/lib/3scale_toolbox/commands/import_command/import_csv.rb b/lib/3scale_toolbox/commands/import_command/import_csv.rb index 977bcd7a..f936909c 100644 --- a/lib/3scale_toolbox/commands/import_command/import_csv.rb +++ b/lib/3scale_toolbox/commands/import_command/import_csv.rb @@ -12,17 +12,17 @@ module ImportCsvSubcommand def self.command Cri::Command.define do name 'csv' - usage 'csv [options]' - summary '3scale CLI import csv' - description '3scale CLI import csv tool' + usage 'csv [opts] -d -f ' + summary 'Import csv file' + description 'Create new services, metrics, methods and mapping rules from CSV formatted file' flag :h, :help, 'show help for this command' do |_, cmd| puts cmd.help exit 0 end - required :d, :destination, 'Destination' - required :f, 'file', 'File' + required :d, :destination, '3scale target instance. Format: "http[s]://@3scale_url"' + required :f, 'file', 'CSV formatted file' run do |opts, args, _| ImportCsvSubcommand.run opts, args diff --git a/lib/3scale_toolbox/commands/update_command.rb b/lib/3scale_toolbox/commands/update_command.rb index d0b0903e..d51726f6 100644 --- a/lib/3scale_toolbox/commands/update_command.rb +++ b/lib/3scale_toolbox/commands/update_command.rb @@ -10,8 +10,8 @@ def self.command Cri::Command.define do name 'update' usage 'update [options]' - summary '3scale CLI update' - description '3scale CLI update tools to manage your API from the terminal.' + summary '3scale update super command' + description '3scale update super command.' flag :h, :help, 'show help for this command' do |_, cmd| puts cmd.help From 4c52022f007c726df1bf43ae2390e9f3fd722e65 Mon Sep 17 00:00:00 2001 From: Eguzki Astiz Lezaun Date: Tue, 23 Oct 2018 14:07:40 +0200 Subject: [PATCH 4/8] README: improve documentation of commands --- README.md | 97 ++++++++++++++++++++++++++++++++++++++++++++++++++++--- 1 file changed, 93 insertions(+), 4 deletions(-) diff --git a/README.md b/README.md index 0adfb593..6a590e83 100644 --- a/README.md +++ b/README.md @@ -12,12 +12,60 @@ Install the CLI: ## Usage ```shell -3scale help +$ 3scale help +NAME + 3scale - 3scale CLI Toolbox + +USAGE + 3scale [options] + +DESCRIPTION + 3scale CLI tools to manage your API from the terminal. + +COMMANDS + copy 3scale copy super command + help show help + import 3scale import super command + update 3scale update super command + +OPTIONS + -k --insecure Proceed and operate even for server connections + otherwise considered insecure + -v --version Prints the version of this command ``` ### Copy a service +Will create a new services, copy existing proxy settings, metrics, methods, application plans and mapping rules. + +Help docstring + +```shell +$ 3scale copy service --help +NAME + service - Copy service + +USAGE + 3scale copy service [opts] -s -d + -Will create a new service, copy existing methods, metrics, application plans and their usage limits. +DESCRIPTION + Will create a new services, copy existing proxy settings, metrics, + methods, application plans and mapping rules. + +OPTIONS + -d --destination= 3scale target instance. Format: + "http[s]://@3scale_url" + -s --source= 3scale source instance. Format: + "http[s]://@3scale_url" + -t --target_system_name= Target system name + +OPTIONS FOR COPY + -h --help show help for this command + -k --insecure Proceed and operate even for server + connections otherwise considered + insecure + -v --version Prints the version of this command +``` ```shell 3scale copy service NUMBER --source=https://provider_key@foo-admin.3scale.net --destination=https://provider_key@foo2-admin.3scale.net @@ -46,7 +94,6 @@ OPTIONS "http[s]://@3scale_url" -f --force Overwrites the mapping rules by deleting all rules from target service first - -h --help show help for this command -r --rules-only Updates only the mapping rules -s --source= 3scale source instance. Format: "http[s]://@3scale_url" @@ -66,7 +113,49 @@ $ 3scale update service -s https://234239874598743@3scaleinstance_source.com -d ### Import from CSV -Will create a new services, metrics, methods and mapping rules. +Will create new services, metrics, methods, and mapping rules having as source comma separated values (CSV) formatted file. + +CSV header + +```csv +service_name,endpoint_name,endpoint_http_method,endpoint_path,auth_mode,endpoint_system_name,type +``` + +File example + +```csv +service_name,endpoint_name,endpoint_http_method,endpoint_path,auth_mode,endpoint_system_name,type +Movies ,Movies (Biography),GET,/movies/biography/,api_key,movies_biography,metric +Movies ,Movies (Drama),GET,/movies/drama/,api_key,movies_drama,method +``` + +Help docstring + +```shell +$ 3scale import csv -h +NAME + csv - Import csv file + +USAGE + 3scale import csv [opts] -d -f + +DESCRIPTION + Create new services, metrics, methods and mapping rules from CSV + formatted file + +OPTIONS + -d --destination= 3scale target instance. Format: + "http[s]://@3scale_url" + -f --file= CSV formatted file + +OPTIONS FOR IMPORT + -h --help show help for this command + -k --insecure Proceed and operate even for server + connections otherwise considered insecure + -v --version Prints the version of this command +``` + +Example: ```shell 3scale import csv --destination=https://provider_key@user-admin.3scale.net --file=examples/import_example.csv From 6ff61451763edd81dd08f31f3b018d80d8026cf4 Mon Sep 17 00:00:00 2001 From: Eguzki Astiz Lezaun Date: Tue, 23 Oct 2018 14:11:46 +0200 Subject: [PATCH 5/8] add global flag for help --- lib/3scale_toolbox/commands/3scale_command.rb | 4 ++++ lib/3scale_toolbox/commands/copy_command.rb | 4 ---- lib/3scale_toolbox/commands/copy_command/copy_service.rb | 5 ----- lib/3scale_toolbox/commands/import_command.rb | 5 ----- lib/3scale_toolbox/commands/import_command/import_csv.rb | 5 ----- lib/3scale_toolbox/commands/update_command.rb | 5 ----- lib/3scale_toolbox/commands/update_command/update_service.rb | 5 ----- 7 files changed, 4 insertions(+), 29 deletions(-) diff --git a/lib/3scale_toolbox/commands/3scale_command.rb b/lib/3scale_toolbox/commands/3scale_command.rb index 103d5ad7..63a51b92 100644 --- a/lib/3scale_toolbox/commands/3scale_command.rb +++ b/lib/3scale_toolbox/commands/3scale_command.rb @@ -17,6 +17,10 @@ def self.command exit end flag :k, :insecure, 'Proceed and operate even for server connections otherwise considered insecure' + flag :h, :help, 'show help for this command' do |_, cmd| + puts cmd.help + exit 0 + end end end end diff --git a/lib/3scale_toolbox/commands/copy_command.rb b/lib/3scale_toolbox/commands/copy_command.rb index 9d8f0c0d..2cb190ac 100644 --- a/lib/3scale_toolbox/commands/copy_command.rb +++ b/lib/3scale_toolbox/commands/copy_command.rb @@ -12,10 +12,6 @@ def self.command usage 'copy [options]' summary '3scale copy super command' description '3scale copy super command.' - flag :h, :help, 'show help for this command' do |_, cmd| - puts cmd.help - exit 0 - end end end add_subcommand(CopyServiceSubcommand) diff --git a/lib/3scale_toolbox/commands/copy_command/copy_service.rb b/lib/3scale_toolbox/commands/copy_command/copy_service.rb index 873b5d8f..dcf4cf90 100644 --- a/lib/3scale_toolbox/commands/copy_command/copy_service.rb +++ b/lib/3scale_toolbox/commands/copy_command/copy_service.rb @@ -13,11 +13,6 @@ def self.command summary 'Copy service' description 'Will create a new services, copy existing proxy settings, metrics, methods, application plans and mapping rules.' - flag :h, :help, 'show help for this command' do |_, cmd| - puts cmd.help - exit 0 - end - required :s, :source, '3scale source instance. Format: "http[s]://@3scale_url"' required :d, :destination, '3scale target instance. Format: "http[s]://@3scale_url"' required :t, 'target_system_name', 'Target system name' diff --git a/lib/3scale_toolbox/commands/import_command.rb b/lib/3scale_toolbox/commands/import_command.rb index 35286b19..3b7b6cd1 100644 --- a/lib/3scale_toolbox/commands/import_command.rb +++ b/lib/3scale_toolbox/commands/import_command.rb @@ -12,11 +12,6 @@ def self.command usage 'import [options]' summary '3scale import super command' description '3scale import super command.' - - flag :h, :help, 'show help for this command' do |_, cmd| - puts cmd.help - exit 0 - end end end add_subcommand(ImportCsvSubcommand) diff --git a/lib/3scale_toolbox/commands/import_command/import_csv.rb b/lib/3scale_toolbox/commands/import_command/import_csv.rb index f936909c..376ea439 100644 --- a/lib/3scale_toolbox/commands/import_command/import_csv.rb +++ b/lib/3scale_toolbox/commands/import_command/import_csv.rb @@ -16,11 +16,6 @@ def self.command summary 'Import csv file' description 'Create new services, metrics, methods and mapping rules from CSV formatted file' - flag :h, :help, 'show help for this command' do |_, cmd| - puts cmd.help - exit 0 - end - required :d, :destination, '3scale target instance. Format: "http[s]://@3scale_url"' required :f, 'file', 'CSV formatted file' diff --git a/lib/3scale_toolbox/commands/update_command.rb b/lib/3scale_toolbox/commands/update_command.rb index d51726f6..a7154064 100644 --- a/lib/3scale_toolbox/commands/update_command.rb +++ b/lib/3scale_toolbox/commands/update_command.rb @@ -12,11 +12,6 @@ def self.command usage 'update [options]' summary '3scale update super command' description '3scale update super command.' - - flag :h, :help, 'show help for this command' do |_, cmd| - puts cmd.help - exit 0 - end end end add_subcommand(UpdateServiceSubcommand) diff --git a/lib/3scale_toolbox/commands/update_command/update_service.rb b/lib/3scale_toolbox/commands/update_command/update_service.rb index 4cb6af02..0191330c 100644 --- a/lib/3scale_toolbox/commands/update_command/update_service.rb +++ b/lib/3scale_toolbox/commands/update_command/update_service.rb @@ -13,11 +13,6 @@ def self.command summary 'Update service' description 'Will update existing service, update proxy settings, metrics, methods, application plans and mapping rules.' - flag :h, :help, 'show help for this command' do |_, cmd| - puts cmd.help - exit 0 - end - required :s, :source, '3scale source instance. Format: "http[s]://@3scale_url"' required :d, :destination, '3scale target instance. Format: "http[s]://@3scale_url"' flag :f, :force, 'Overwrites the mapping rules by deleting all rules from target service first' From 6446c90087907d63dfacaddc086abf63813bbef2 Mon Sep 17 00:00:00 2001 From: Eguzki Astiz Lezaun Date: Tue, 23 Oct 2018 14:14:33 +0200 Subject: [PATCH 6/8] README: minor fix in doc --- README.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/README.md b/README.md index 6a590e83..6fdf363c 100644 --- a/README.md +++ b/README.md @@ -37,7 +37,7 @@ OPTIONS ### Copy a service Will create a new services, copy existing proxy settings, metrics, methods, application plans and mapping rules. -Help docstring +Help message: ```shell $ 3scale copy service --help @@ -75,7 +75,7 @@ OPTIONS FOR COPY Will update existing service, update proxy settings, metrics, methods, application plans and mapping rules. -Help docstring +Help message: ```shell NAME @@ -129,7 +129,7 @@ Movies ,Movies (Biography),GET,/movies/biography/,api_key,movies_biography,metri Movies ,Movies (Drama),GET,/movies/drama/,api_key,movies_drama,method ``` -Help docstring +Help message: ```shell $ 3scale import csv -h From a77dd5e1007d3c43a721029154ce055474ab5e41 Mon Sep 17 00:00:00 2001 From: Eguzki Astiz Lezaun Date: Tue, 23 Oct 2018 15:14:42 +0200 Subject: [PATCH 7/8] Minor doc fix. Remove misleading super term. --- README.md | 8 ++++---- lib/3scale_toolbox/commands/copy_command.rb | 4 ++-- lib/3scale_toolbox/commands/import_command.rb | 4 ++-- lib/3scale_toolbox/commands/update_command.rb | 4 ++-- 4 files changed, 10 insertions(+), 10 deletions(-) diff --git a/README.md b/README.md index 6fdf363c..4b662422 100644 --- a/README.md +++ b/README.md @@ -23,10 +23,10 @@ DESCRIPTION 3scale CLI tools to manage your API from the terminal. COMMANDS - copy 3scale copy super command + copy 3scale copy command help show help - import 3scale import super command - update 3scale update super command + import 3scale import command + update 3scale update command OPTIONS -k --insecure Proceed and operate even for server connections @@ -108,7 +108,7 @@ OPTIONS FOR UPDATE Example: ```shell -$ 3scale update service -s https://234239874598743@3scaleinstance_source.com -d https://2342342342342@3scaleinstance_destination.com 3 2 +$ 3scale update service -s https://9874598743@source.example.com -d https://2342342342342@destination.example.com 3 2 ``` ### Import from CSV diff --git a/lib/3scale_toolbox/commands/copy_command.rb b/lib/3scale_toolbox/commands/copy_command.rb index 2cb190ac..2d48ddea 100644 --- a/lib/3scale_toolbox/commands/copy_command.rb +++ b/lib/3scale_toolbox/commands/copy_command.rb @@ -10,8 +10,8 @@ def self.command Cri::Command.define do name 'copy' usage 'copy [options]' - summary '3scale copy super command' - description '3scale copy super command.' + summary '3scale copy command' + description '3scale copy command.' end end add_subcommand(CopyServiceSubcommand) diff --git a/lib/3scale_toolbox/commands/import_command.rb b/lib/3scale_toolbox/commands/import_command.rb index 3b7b6cd1..4521b54c 100644 --- a/lib/3scale_toolbox/commands/import_command.rb +++ b/lib/3scale_toolbox/commands/import_command.rb @@ -10,8 +10,8 @@ def self.command Cri::Command.define do name 'import' usage 'import [options]' - summary '3scale import super command' - description '3scale import super command.' + summary '3scale import command' + description '3scale import command.' end end add_subcommand(ImportCsvSubcommand) diff --git a/lib/3scale_toolbox/commands/update_command.rb b/lib/3scale_toolbox/commands/update_command.rb index a7154064..dd6d44ca 100644 --- a/lib/3scale_toolbox/commands/update_command.rb +++ b/lib/3scale_toolbox/commands/update_command.rb @@ -10,8 +10,8 @@ def self.command Cri::Command.define do name 'update' usage 'update [options]' - summary '3scale update super command' - description '3scale update super command.' + summary '3scale update command' + description '3scale update command.' end end add_subcommand(UpdateServiceSubcommand) From 2d000c07d5b8b5dab5471f8ea2d1412a98a6e2b3 Mon Sep 17 00:00:00 2001 From: Eguzki Astiz Lezaun Date: Tue, 23 Oct 2018 15:18:33 +0200 Subject: [PATCH 8/8] README: add TOC --- README.md | 13 +++++++++++-- 1 file changed, 11 insertions(+), 2 deletions(-) diff --git a/README.md b/README.md index 4b662422..35c5e651 100644 --- a/README.md +++ b/README.md @@ -2,9 +2,18 @@ 3scale toolbox is a set of tools to help you manage your 3scale product. Using the [3scale API Ruby Client](https://github.com/3scale/3scale-api-ruby). -## Installation - +## Table of contents +* [Installation](#installation) +* [Usage](#usage) + * [Copy a service](#copy-a-service) + * [Update a service](#update-a-service) + * [Import from CSV](#import-from-csv) +* [Development](#development) +* [Plugins](#plugins) +* [Troubleshooting](#troubleshooting) +* [Contributing](#contributing) +## Installation Install the CLI: $ gem install 3scale_toolbox