Flesh out documention on how `json-body` works

[wfchandler]

Currently we provide a few examples of using --json-body with CLI commands in https://docs.oxide.computer/cli/guides/introduction, but don't get into the details of how we expect it to be used.

We should document:

• When a value is specified as an --<ARG> and in the JSON body, which one is used?
• Which commands require it?
• Guidance on when we recommend using it.

[sion42x]

Documenting some answers to this for future reference.

The --json-body-template flag is a stub

The --json-body-template argument was added as a placeholder but not yet implemented. You can see it in progenitor's CLI generation code: https://github.com/oxidecomputer/progenitor/blob/main/progenitor-impl/src/cli.rs#L489-L494

rust.arg(
    ::clap::Arg::new("json-body-template")
        .long("json-body-template")
        .action(::clap::ArgAction::SetTrue)
        .help("XXX")
)

This was part of the initial CLI generation work tracked in oxidecomputer/progenitor#289, which mentions:

The help message should make the full post body schema explicit and there should be an option to output a template to make it easy for consumers to fill in the blanks.

Deriving templates

The templates can be derived from the OpenAPI spec at oxide.json. For any command that takes --json-body, you can find the schema in #/components/schemas/<TypeName>. For example, instance create uses the InstanceCreate schema.

Q&A

1. When a value is specified as an --<ARG> and in the JSON body, which one is used?

CLI args for body properties use body_map() to set individual fields: https://github.com/oxidecomputer/progenitor/blob/main/progenitor-impl/src/cli.rs#L585-L597

But the --json-body consumer calls request.body(body_value) which replaces the entire body: https://github.com/oxidecomputer/progenitor/blob/main/progenitor-impl/src/cli.rs#L507-L523

These are combined with CLI args first, then JSON body after: https://github.com/oxidecomputer/progenitor/blob/main/progenitor-impl/src/cli.rs#L525-L530

So if you specify both, the JSON body file wins and any CLI args for body properties are effectively ignored.

2. Which commands require it?

Commands require --json-body when the request body contains nested objects or arrays that can't be expressed as simple CLI flags. If a body property doesn't implement FromStr (i.e., it's not a simple scalar type) and is required, the body becomes required: https://github.com/oxidecomputer/progenitor/blob/main/progenitor-impl/src/cli.rs#L570-L600

3. Guidance on when we recommend using it

This needs documentation! Currently it's only necessary for complex nested structures. Some commands have been hand-optimized in oxide.rs to avoid this (e.g., ip-pool range add adds --first and --last flags): https://github.com/oxidecomputer/oxide.rs/blob/main/cli/src/cli_builder.rs#L118-L136