Add jf api docs describe for OpenAPI operation detail lookup

[ehl-jf]

jf api docs describe — full operation detail lookup

Follow-up to jf api docs search (#3597 / JGC-526). Search finds a candidate endpoint by
keyword; this PR adds a second jf api docs subcommand to see that endpoint's full shape
before calling it — parameters, request body schema, response codes, and (when the spec
declares one) an example payload — still fully local and offline, no server configuration or
network call involved.

$ jf api docs describe GET /access/api/v2/users
{
  "spec_bundle": "stub",
  "spec_version": "",
  "method": "GET",
  "path": "/access/api/v2/users",
  "summary": "Get User List",
  "tags": ["Users"],
  "parameters": [
    {"name": "status", "in": "query", "required": false, "description": "Filter users by status"},
    ...
  ],
  "responses": [
    {"code": "200", "description": "Success"},
    {"code": "400", "description": "Bad Request - Invalid input, object invalid"},
    ...
  ],
  "jf_api": "jf api /access/api/v2/users"
}

$ jf api docs describe POST /access/api/v2/users --format table
METHOD        POST
PATH          /access/api/v2/users
SUMMARY       Create User
TAGS          Users
PARAMETERS    -
REQUEST BODY  admin,disable_ui_access,email*,groups,internal_password_disabled,password,profile_updatable,username*
RESPONSES     201:User created successfully, 400:Bad Request - Invalid input, object invalid, ...
JF API        jf api /access/api/v2/users -X POST -H "Content-Type: application/json" -d '{"email":"","username":""}'

The intended flow this unlocks for an agent (or a human) is:

$ jf api docs search trust
# ... pick a method+path from the results, e.g. PUT /bridge-client/api/v1/service_trust/pairing/bridge/{bridge_id} ...

$ jf api docs describe PUT "/bridge-client/api/v1/service_trust/pairing/bridge/{bridge_id}"
{
  ...
  "request_body": {
    "required": true,
    "properties": [{"name": "pairing_token", "type": "string", "required": true, "description": "A valid pairing token generated on the Bridge Server JPD"}],
    "example": {"pairing_token": "eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiJ9..."}
  },
  "jf_api": "jf api /bridge-client/api/v1/service_trust/pairing/bridge/{bridge_id} -X PUT -H \"Content-Type: application/json\" -d '{\"pairing_token\":\"\"}'"
}

— search → describe → construct and run the real jf api call, without ever having to guess
at an endpoint's shape.

Behavior

• Exact lookup, not a search. Takes a literal method + path (case-insensitive method,
  leading / optional) and returns that one operation, or a clear non-zero-exit error naming
  the searched spec_bundle and pointing back to jf api docs search if it's not in the
  catalog. This is a deliberate contrast with docs search, which returns an empty match list
  with exit 0 — describe targets a single, specific operation, so "not found" is a caller
  mistake worth failing on.
• JSON is the unconditional default output format (--format table also available),
  matching docs search's existing convention rather than gating on --ai-help.
• Request body examples. The OpenAPI parser (docs/api-spec) now also captures each
  operation's declared responses (code + description) and, when present, the request body's
  media-type-level example. Both are rare in the trimmed OSS stub bundle but real in the full
  internal bundle — verified against the actual rdme-admin reference spec, not just synthetic
  fixtures.
• Reuses the same jf_api one-liner construction as docs search — the two commands stay
  byte-for-byte consistent for the same operation.
• jf api --ai-help and the docs/docs search help text now reference the full
  search → describe → execute chain, and no longer claim "OpenAPI bundles are not shipped with
  the CLI" (stale since JGC-525/526 landed).

Testing

Ran the full QA pass manually against both the stub build and a full build (375 real operations,
rdme-admin reference bundle) built via the internal make full flow: exact-lookup success/
not-found cases, case-insensitivity, table/JSON rendering, help text, and an end-to-end
search → describe → construct-a-real-call scenario against a real Bridge API operation,
confirming the surfaced parameters/request body/example match the actual spec and that
docs search's and docs describe's jf_api one-liners agree exactly.

---

• All tests have passed. If this feature is not already covered by the tests, new tests have been added.
• The pull request is targeting the master branch.
• The code has been validated to compile successfully by running go vet ./....
• The code has been formatted properly using go fmt ./....

[github-actions]

---

🐸 JFrog Frogbot