Transit read-key response documentation omits `latest_version`

Start with the Read Key page linked in the issue and compare its response example with the live GET /v1/transit/keys/:name response. Inspect /v1/sys/internal/specs/openapi for the corresponding 200 response. Done means the page and sample document latest_version, with its presence and bounds clarified, and the OpenAPI response gap addressed or explicitly scoped.

Describe the bug

GET /v1/transit/keys/:name returns a latest_version field, but it is not documented anywhere:

1. The Read Key page does not mention it, and the sample response omits it.
2. The OpenAPI spec from /v1/sys/internal/specs/openapi has no response body definition for this endpoint — the 200 is a bare "description": "OK" with no schema reference.
   The field is only discoverable by calling the endpoint.

Steps to reproduce

Against hashicorp/vault:2.0.4 in dev mode, with transit enabled:

$ vault write -f transit/keys/foo
$ curl -sH "X-Vault-Token: $VAULT_TOKEN" "$VAULT_ADDR/v1/transit/keys/foo" \
    | jq '.data | {name, latest_version, keys}'
{
  "name": "foo",
  "latest_version": 1,
  "keys": { "1": 1787846981 }
}

$ vault write -f transit/keys/foo/rotate
$ curl -sH "X-Vault-Token: $VAULT_TOKEN" "$VAULT_ADDR/v1/transit/keys/foo" \
    | jq '.data | {name, latest_version, keys}'
{
  "name": "foo",
  "latest_version": 2,
  "keys": { "1": 1787846981, "2": 1787846983 }
}

Confirming the spec describes no response fields:

$ curl -sH "X-Vault-Token: $VAULT_TOKEN" "$VAULT_ADDR/v1/sys/internal/specs/openapi" \
    | jq '.paths."/transit/keys/{name}".get.responses'
{ "200": { "description": "OK" } }

Why this matters

We depend on latest_version to detect Transit key rotation. Because it is undocumented, a reviewer questioned whether we should rely on it, and suggested deriving the current version from the largest key of the keys map instead.

We would prefer the scalar. The keys map returns version numbers as JSON object keys, so they must be parsed from strings before comparison, and its value shape appears to vary by key type. A documented scalar is easier to depend on.

Requests

1. Please document latest_version on the Read Key page, including in the sample response.
2. Is latest_version guaranteed present for all key types, and always >= 1 for a key that exists? We currently treat absence as an error and assume no lower bound — min_encryption_version is documented in the same response as using 0 as a sentinel for "use the latest version", so we did not want to assume 0 is impossible here without confirmation.
3. Are response schemas for the Transit endpoints planned for the generated OpenAPI spec? That would resolve this class of question generally.

Vault version

Vault v2.0.4 (c9e9d1d4ddd4b55aae79a8949adffa9e96338720), built 2026-08-03T16:14:36Z