feat(api): Group commands by openapi tag

[wdullaer]

Cobra recently added support for command groups.

I have used it for 2 things:

• I removed the custom help template: the comment there indicated this was a placeholder for command groups anyway. The built-in commands have been groups to match the original help. I did not add a group for help and completion. They can be put in the generic group, but I quite liked that they ended up under Additional Commands
  Example

➜ ./restish -h

  A generic client for REST-ish APIs https://rest.sh/                                                                                                                                                            



Usage:
  restish [flags]
  restish [command]

Examples:
  # Get a URI
  $ restish google.com

  # Specify verb, header, and body shorthand
  $ restish post :8888/users -H authorization:abc123 name: Kari, role: admin

Available API Commands:
  pet-store https://example.com/api
  my-api    http://localhost:8090/api

Generic Commands:
  api          API management commands
  auth-header  Get an auth header for a given API
  cert         Get cert info
  delete       Delete a URI
  edit         Edit a resource by URI
  get          Get a URI
  head         Head a URI
  links        Get link relations from the given URI, with optional filtering
  options      Options a URI
  patch        Patch a URI
  post         Post a URI
  put          Put a URI

Additional Commands:
  completion   Generate the autocompletion script for the specified shell
  help         Help about any command

Flags:
  -h, --help                       help for restish
      --rsh-ca-cert string         Path to a PEM encoded CA cert
      --rsh-client-cert string     Path to a PEM encoded client certificate
      --rsh-client-key string      Path to a PEM encoded private key
  -f, --rsh-filter string          Filter / project results using JMESPath Plus
  -H, --rsh-header strings         Add custom header
      --rsh-insecure               Disable SSL verification
      --rsh-no-cache               Disable HTTP cache
      --rsh-no-paginate            Disable auto-pagination
  -o, --rsh-output-format string   Output format [auto, json, yaml] (default "auto")
  -p, --rsh-profile string         API auth profile (default "default")
  -q, --rsh-query strings          Add custom query param
  -r, --rsh-raw                    Output result of query as raw rather than an escaped JSON string or list
  -s, --rsh-server string          Override scheme://server:port for an API
  -t, --rsh-table                  Enable table formatted output for array of objects
  -v, --rsh-verbose                Enable verbose log output
      --version                    version for restish

Use "restish [command] --help" for more information about a command.

• Group commands together based on openapi operation tags
  Because a command can have multiple tags, but only 1 group, I'm just selecting the first tag. A bit of a spot check for APIs in the wild seems to indicate that most APIs use tags in this way. APIs which do not have any groups will have their restish command list render exactly the same way

Example:

➜ ./restish pet-store -h

  Swagger Petstore                                                                                                                                                                                   




Pets Commands:
  listPets            
  createPets
  showPetsById           

Flags:
  -h, --help   help for pet-store

Global Flags:
      --rsh-ca-cert string         Path to a PEM encoded CA cert
      --rsh-client-cert string     Path to a PEM encoded client certificate
      --rsh-client-key string      Path to a PEM encoded private key
  -f, --rsh-filter string          Filter / project results using JMESPath Plus
  -H, --rsh-header strings         Add custom header
      --rsh-insecure               Disable SSL verification
      --rsh-no-cache               Disable HTTP cache
      --rsh-no-paginate            Disable auto-pagination
  -o, --rsh-output-format string   Output format [auto, json, yaml] (default "auto")
  -p, --rsh-profile string         API auth profile (default "default")
  -q, --rsh-query strings          Add custom query param
  -r, --rsh-raw                    Output result of query as raw rather than an escaped JSON string or list
  -s, --rsh-server string          Override scheme://server:port for an API
  -t, --rsh-table                  Enable table formatted output for array of objects
  -v, --rsh-verbose                Enable verbose log output

Use "restish pet-store [command] --help" for more information about a command.

It looks a bit overkill on the example, but we have multiple APIs with over 25 commands each, and the grouping really helps there.

If this is deemed to invasive, I'm happy to investigate and contribute an api level config option for this behaviour.

[danielgtaylor]

This is awesome, thanks @wdullaer! I tried this on a number of both public and private APIs and it works really well and simplifies the code! Example output for api.rest.sh:

Usage:
  restish example [flags]
  restish example [command]

Cached Commands:
  get-cached        Cached response example

Example Commands:
  get-example       Example large structured data response
  get-types-example Example structured data types
  put-types-example Example write for edits

Images Commands:
  get-image         Get an image
  list-images       Paginated list of all images

Echo Commands:
  delete-echo       Echo DELETE
  get-echo          Echo GET
  patch-echo        Echo PATCH
  post-echo         Echo POST
  put-echo          Echo PUT