Merge pull request #63 from 3scale/doc/update-service

Toolbox documentation

README.md

@@ -2,30 +2,169 @@
 
 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
 
 ## Usage
 
 ```shell
-3scale help
+$ 3scale help
+NAME
+    3scale - 3scale CLI Toolbox
+
+USAGE
+    3scale <command> [options]
+
+DESCRIPTION
+    3scale CLI tools to manage your API from the terminal.
+
+COMMANDS
+    copy       3scale copy command
+    help       show help
+    import     3scale import command
+    update     3scale update 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.
 
-Will create a new service, copy existing methods, metrics, application plans and their usage limits.
+Help message:
+
+```shell
+$ 3scale copy service --help
+NAME
+    service - Copy service
+
+USAGE
+    3scale copy service [opts] -s <src> -d <dst>
+    <service_id>
+
+DESCRIPTION
+    Will create a new services, copy existing proxy settings, metrics,
+    methods, application plans and mapping rules.
+
+OPTIONS
+    -d --destination=<value>             3scale target instance. Format:
+                                         "http[s]://<provider_key>@3scale_url"
+    -s --source=<value>                  3scale source instance. Format:
+                                         "http[s]://<provider_key>@3scale_url"
+    -t --target_system_name=<value>      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://[email protected] --destination=https://[email protected]
 ```
 
+### Update a service
+
+Will update existing service, update proxy settings, metrics, methods, application plans and mapping rules.
+
+Help message:
+
+```shell
+NAME
+    service - Update service
+
+USAGE
+    3scale update service [opts] -s <src> -d <dst>
+    <src_service_id> <dst_service_id>
+
+DESCRIPTION
+    Will update existing service, update proxy settings, metrics, methods,
+    application plans and mapping rules.
+
+OPTIONS
+    -d --destination=<value>      3scale target instance. Format:
+                                  "http[s]://<provider_key>@3scale_url"
+    -f --force                    Overwrites the mapping rules by deleting
+                                  all rules from target service first
+    -r --rules-only               Updates only the mapping rules
+    -s --source=<value>           3scale source instance. Format:
+                                  "http[s]://<provider_key>@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://[email protected] -d https://[email protected] 3 2
+```
+
 ### 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 message:
+
+```shell
+$ 3scale import csv -h
+NAME
+    csv - Import csv file
+
+USAGE
+    3scale import csv [opts] -d <dst> -f <file>
+
+DESCRIPTION
+    Create new services, metrics, methods and mapping rules from CSV
+    formatted file
+
+OPTIONS
+    -d --destination=<value>      3scale target instance. Format:
+                                  "http[s]://<provider_key>@3scale_url"
+    -f --file=<value>             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://[email protected] --file=examples/import_example.csv

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

lib/3scale_toolbox/commands/copy_command.rb

@@ -10,12 +10,8 @@ def self.command
         Cri::Command.define do
           name        'copy'
           usage       'copy <command> [options]'
-          summary     '3scale CLI copy'
-          description '3scale CLI copy tools to manage your API from the terminal.'
-          flag :h, :help, 'show help for this command' do |_, cmd|
-            puts cmd.help
-            exit 0
-          end
+          summary     '3scale copy command'
+          description '3scale copy command.'
         end
       end
       add_subcommand(CopyServiceSubcommand)

lib/3scale_toolbox/commands/copy_command/copy_service.rb

@@ -9,17 +9,12 @@ module CopyServiceSubcommand
         def self.command
           Cri::Command.define do
             name        'service'
-            usage       'service [options] <service_id>'
-            summary     '3scale CLI copy service'
-            description '3scale CLI copy service tool'
+            usage       'service [opts] -s <src> -d <dst> <service_id>'
+            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]://<provider_key>@3scale_url"'
+            required  :d, :destination, '3scale target instance. Format: "http[s]://<provider_key>@3scale_url"'
             required  :t, 'target_system_name', 'Target system name'
 
             run do |opts, args, _|

lib/3scale_toolbox/commands/import_command.rb

@@ -10,13 +10,8 @@ def self.command
         Cri::Command.define do
           name        'import'
           usage       'import <command> [options]'
-          summary     '3scale CLI import'
-          description '3scale CLI import tools to manage your API from the terminal.'
-
-          flag :h, :help, 'show help for this command' do |_, cmd|
-            puts cmd.help
-            exit 0
-          end
+          summary     '3scale import command'
+          description '3scale import command.'
         end
       end
       add_subcommand(ImportCsvSubcommand)

lib/3scale_toolbox/commands/import_command/import_csv.rb

@@ -12,17 +12,12 @@ 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 <dst> -f <file>'
+            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]://<provider_key>@3scale_url"'
+            required  :f, 'file', 'CSV formatted file'
 
             run do |opts, args, _|
               ImportCsvSubcommand.run opts, args

lib/3scale_toolbox/commands/update_command.rb

@@ -10,13 +10,8 @@ def self.command
         Cri::Command.define do
           name        'update'
           usage       'update <command> [options]'
-          summary     '3scale CLI update'
-          description '3scale CLI update tools to manage your API from the terminal.'
-
-          flag :h, :help, 'show help for this command' do |_, cmd|
-            puts cmd.help
-            exit 0
-          end
+          summary     '3scale update command'
+          description '3scale update command.'
         end
       end
       add_subcommand(UpdateServiceSubcommand)

lib/3scale_toolbox/commands/update_command/update_service.rb

@@ -9,19 +9,13 @@ module UpdateServiceSubcommand
         def self.command
           Cri::Command.define do
             name        'service'
-            usage       'service [options] <service_id>'
-            summary     '3scale CLI update service'
-            description '3scale CLI update service tool'
+            usage       'service [opts] -s <src> -d <dst> <src_service_id> <dst_service_id>'
+            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]://<provider_key>@3scale_url"'
+            required  :d, :destination, '3scale target instance. Format: "http[s]://<provider_key>@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, _|