Generate Markdown files of commands

[Jonesy]

To cut down on duplicating sources of truth, write a Go build script to generate Markdown files from each cmd/command_file.go file which can either be hosted in Github pages or a hosted government website.

[Jonesy]

Preview of the generated documentation below in next comment. It's just with what I have now but will be filled out soon with full documentation. Any feedback regarding layout or structure please let me know @ikethecoder , @JohnathanBrammall .

I think we should plan to run the generate command each production build, I just want to coordinate with the team working on Backstage to coordinate the best way to do that, I'll reach out to the DevEx team to see what the best way to do that is.

[Jonesy]

GWA CLI Commands

apply

Usage: gwa apply <type> [flags]

Flags

Flag	Description
-i, --input string	YAML file containing your configuration (default "gw-config.yml")

Examples

$ gwa apply --input gw-config.yaml

config

Usage: gwa config

config.get

Usage: gwa config get [key]

config.set

Exposes some specific config values that can be defined by the user.

Configurable Settings:
namespace: The default namespace used
token: Use only if you have a token you know is authenticated
host: The API host you wish to communicate with
scheme: http or https

Usage: gwa config set [key] [value] [flags]

Flags

Flag	Description
--host string	set the host
--namespace string	set the namespace
--scheme string	set the scheme
--token string	set the namespace

Examples

$ gwa config set namespace ns-sampler
$ gwa config set --namespace ns-sampler

generate-config

Usage: gwa generate-config [flags]

Flags

Flag	Description
--org string	Set the organization (default "ministry-of-citizens-services")
--org-unit string	Set the organization unit (default "databc")
-o, --out string	The file to output the generate config to (default "gw-config.yml")
-s, --service string	A unique service subdomain for your vanity url: https://.api.gov.bc.ca
-t, --template string	Name of a pre-defined template (kong-httpbin, client-credentials-shared-idp)
-u, --upstream string	The upstream implementation of the API

Examples

$ gwa generate-config --template kong-httpbin --service my-service --upstream https://httpbin.org
$ gwa generate-config --template client-credentials-shared-idp --service my-service --upstream https://www.boredapi.com/api/activity

get

Usage: gwa get [type] <flags> [flags]

Flags

Flag	Description
--json	Return output as JSON
--yaml	Return output as YAML

Examples

$ gwa get datasets
$ gwa get datasets --json
$ gwa get datasets --yaml

init

Generates a .env file in the current working directory.

To create and work with configurations you don't require CLIENT_ID or CLIENT_SECRET, but to make any API requests you will

Usage: gwa init [flags]

Flags

Flag	Description
--api-version int	Set the API version (default 2)
--client-id string	Namespace's Client ID from API Services Portal
--client-secret string	Namespace's Client Secret from API Services Portal
-d, --data-center string	Target a particular data centre (default "calgary")
-D, --dev	Set the environment as development
--ds-api-version int	Set the Directory API version (default 2)
-n, --namespace string	The namespace of you routes collection (required)
-P, --prod	Set the environment as production
-T, --test	Set the environment as test

login

You can login via device login or by using client credentials.

Usage: gwa login [flags]

Flags

Flag	Description
--client-id string	Your gateway's client ID
--client-secret string	Your gateway's client secret

Examples

$ gwa login
$ gwa login --client-id <YOUR_CLIENT_ID> --client-secret <YOUR_CLIENT_SECRET>

namespace

Longer explanation to come...

Usage: gwa namespace

namespace.create

Usage: gwa namespace create [flags]

Flags

Flag	Description
-d, --description string	optionally add a description
-n, --name string	optionally define your own namespace

namespace.current

Usage: gwa namespace current

namespace.destroy

Usage: gwa namespace destroy [flags]

Flags

Flag	Description
--force	force deletion

namespace.list

Usage: gwa namespace list

publish

Usage: gwa publish <type> [flags]

Flags

Flag	Description
-i, --input string	YAML file to convert to JSON

Examples

$ gwa publish dataset --input content.yaml
$ gwa publish product --input content.yaml
$ gwa publish issuer --input content.yaml

publish-gateway

Usage: gwa publish-gateway [configFile] [flags]

Flags

Flag	Description
--dry-run	Dry run your API changes before committing to them
--qualifier string	Sets a tag qualifier, which specifies that the gateway configuration is a partial set of configuration

Examples

  $ gwa publish-gateway path/to/config.yaml
  $ gwa publish-gateway path/to/config.yaml --dry-run

status

Usage: gwa status [flags]

Flags

Flag	Description
--json	Output status as a JSON string

Examples

  $ gwa status
  $ gwa status --json

[Jonesy]

I have connected with Monica from the Dev Experience team and they want us to confirm the following:

• How often do you update the documentation?
◦ If it is a regular occurrence, I'll look at writing a script to keep the developer-portal docs in sync with your main docs
• Can I make a branch on your repo to check in my changes for the developer-portal? Or would you prefer I fork your repo?