[DOCS] Document `bytes` and `time` params in cat API docs (#47672) (#47854)

docs/reference/cat/alias.asciidoc

@@ -11,12 +11,16 @@ filter and routing information.
 [[cat-alias-api-request]]
 ==== {api-request-title}
 
-`GET /_cat/aliases/<name>`
+`GET /_cat/aliases/<alias>`
+
+`GET /_cat/aliases`
 
 [[cat-alias-api-path-params]]
 ==== {api-path-parms-title}
 
-include::{docdir}/rest-api/common-parms.asciidoc[tag=name]
+`<alias>`::
+(Optional, string)
+include::{docdir}/rest-api/common-parms.asciidoc[tag=index-alias]
 
 
 [[cat-alias-api-query-params]]

docs/reference/cat/allocation.asciidoc

@@ -14,6 +14,8 @@ and their disk space.
 
 `GET /_cat/allocation/<node_id>`
 
+`GET /_cat/allocation`
+
 [[cat-allocation-api-path-params]]
 ==== {api-path-parms-title}
 

docs/reference/cat/count.asciidoc

@@ -16,6 +16,8 @@ which have not yet been removed by the merge process.
 
 `GET /_cat/count/<index>`
 
+`GET /_cat/count`
+
 
 [[cat-count-api-path-params]]
 ==== {api-path-parms-title}

docs/reference/cat/fielddata.asciidoc

@@ -13,6 +13,8 @@ in the cluster.
 
 `GET /_cat/fielddata/<field>`
 
+`GET /_cat/fielddata`
+
 
 [[cat-fielddata-api-path-params]]
 ==== {api-path-parms-title}

docs/reference/cat/health.asciidoc

@@ -51,6 +51,8 @@ include::{docdir}/rest-api/common-parms.asciidoc[tag=master-timeout]
 
 include::{docdir}/rest-api/common-parms.asciidoc[tag=cat-s]
 
+include::{docdir}/rest-api/common-parms.asciidoc[tag=time]
+
 `ts` (timestamps)::
 (Optional, boolean) If `true`, returns `HH:MM:SS` and
 https://en.wikipedia.org/wiki/Unix_time[Unix `epoch`] timestamps. Defaults to

docs/reference/cat/indices.asciidoc

@@ -12,6 +12,8 @@ Returns high-level information about indices in a cluster.
 
 `GET /_cat/indices/<index>`
 
+`GET /_cat/indices`
+
 
 [[cat-indices-api-desc]]
 ==== {api-description-title}
@@ -77,6 +79,8 @@ primary shards. Defaults to `false`.
 
 include::{docdir}/rest-api/common-parms.asciidoc[tag=cat-s]
 
+include::{docdir}/rest-api/common-parms.asciidoc[tag=time]
+
 include::{docdir}/rest-api/common-parms.asciidoc[tag=cat-v]
 
 

docs/reference/cat/nodes.asciidoc

@@ -14,6 +14,8 @@ Returns information about a cluster's nodes.
 [[cat-nodes-api-query-params]]
 ==== {api-query-parms-title}
 
+include::{docdir}/rest-api/common-parms.asciidoc[tag=bytes]
+
 include::{docdir}/rest-api/common-parms.asciidoc[tag=http-format]
 
 `full_id`::
@@ -287,6 +289,8 @@ include::{docdir}/rest-api/common-parms.asciidoc[tag=master-timeout]
 
 include::{docdir}/rest-api/common-parms.asciidoc[tag=cat-s]
 
+include::{docdir}/rest-api/common-parms.asciidoc[tag=time]
+
 include::{docdir}/rest-api/common-parms.asciidoc[tag=cat-v]
 
 

docs/reference/cat/pending_tasks.asciidoc

@@ -27,6 +27,8 @@ include::{docdir}/rest-api/common-parms.asciidoc[tag=master-timeout]
 
 include::{docdir}/rest-api/common-parms.asciidoc[tag=cat-s]
 
+include::{docdir}/rest-api/common-parms.asciidoc[tag=time]
+
 include::{docdir}/rest-api/common-parms.asciidoc[tag=cat-v]
 
 

docs/reference/cat/recovery.asciidoc

@@ -56,6 +56,8 @@ include::{docdir}/rest-api/common-parms.asciidoc[tag=master-timeout]
 
 include::{docdir}/rest-api/common-parms.asciidoc[tag=cat-s]
 
+include::{docdir}/rest-api/common-parms.asciidoc[tag=time]
+
 include::{docdir}/rest-api/common-parms.asciidoc[tag=cat-v]
 
 

docs/reference/cat/segments.asciidoc

@@ -13,6 +13,8 @@ API.
 
 `GET /_cat/segments/<index>`
 
+`GET /_cat/segments`
+
 
 [[cat-segments-path-params]]
 ==== {api-path-parms-title}

docs/reference/cat/shards.asciidoc

@@ -14,6 +14,8 @@ docs, the bytes it takes on disk, and the node where it's located.
 
 `GET /_cat/shards/<index>`
 
+`GET /_cat/shards`
+
 
 [[cat-shards-path-params]]
 ==== {api-path-parms-title}
@@ -269,6 +271,8 @@ include::{docdir}/rest-api/common-parms.asciidoc[tag=master-timeout]
 
 include::{docdir}/rest-api/common-parms.asciidoc[tag=cat-s]
 
+include::{docdir}/rest-api/common-parms.asciidoc[tag=time]
+
 include::{docdir}/rest-api/common-parms.asciidoc[tag=cat-v]
 
 

docs/reference/cat/snapshots.asciidoc

@@ -13,6 +13,8 @@ more repositories. A snapshot is a backup of an index or running {es} cluster.
 
 `GET /_cat/snapshots/<repository>`
 
+`GET /_cat/snapshots`
+
 
 [[cat-snapshots-path-params]]
 ==== {api-path-parms-title}
@@ -103,6 +105,8 @@ include::{docdir}/rest-api/common-parms.asciidoc[tag=master-timeout]
 
 include::{docdir}/rest-api/common-parms.asciidoc[tag=cat-s]
 
+include::{docdir}/rest-api/common-parms.asciidoc[tag=time]
+
 include::{docdir}/rest-api/common-parms.asciidoc[tag=cat-v]
 
 

docs/reference/cat/tasks.asciidoc

@@ -57,6 +57,8 @@ include::{docdir}/rest-api/common-parms.asciidoc[tag=parent-task-id]
 
 include::{docdir}/rest-api/common-parms.asciidoc[tag=cat-s]
 
+include::{docdir}/rest-api/common-parms.asciidoc[tag=time]
+
 include::{docdir}/rest-api/common-parms.asciidoc[tag=wait_for_completion]
 
 include::{docdir}/rest-api/common-parms.asciidoc[tag=cat-v]

docs/reference/cat/templates.asciidoc

@@ -14,6 +14,8 @@ and <<mapping,field mappings>> to new indices at creation.
 
 `GET /_cat/templates/<template_name>`
 
+`GET /_cat/templates`
+
 
 [[cat-templates-path-params]]
 ==== {api-path-parms-title}

docs/reference/cat/thread_pool.asciidoc

@@ -14,6 +14,9 @@ pools.
 
 `GET /_cat/thread_pool/<thread_pool>`
 
+`GET /_cat/thread_pool`
+
+
 [[cat-thread-pool-path-params]]
 ==== {api-path-parms-title}
 

docs/reference/rest-api/common-parms.asciidoc

@@ -446,11 +446,6 @@ such as `1264`.
 A value of `-1` indicates {es} was unable to compute this number.
 end::memory[]
 
-tag::name[]
-`<name>`::
-(Optional, string) Comma-separated list of alias names to return.
-end::name[]
-
 tag::node-id[]
 `<node_id>`::
 (Optional, string) Comma-separated list of node IDs or names used to limit
@@ -696,6 +691,12 @@ tag::terminate_after[]
 upon reaching which the query execution will terminate early.
 end::terminate_after[]
 
+tag::time[]
+`time`::
+(Optional, <<time-units,time units>>)
+Unit used to display time values.
+end::time[]
+
 tag::timeoutparms[]
 
 tag::timeout[]

rest-api-spec/src/main/resources/rest-api-spec/api/cat.health.json

@@ -41,6 +41,19 @@
         "type":"list",
         "description":"Comma-separated list of column names or column aliases to sort by"
       },
+      "time":{
+        "type":"enum",
+        "description":"The unit in which to display time values",
+        "options":[
+          "d (Days)",
+          "h (Hours)",
+          "m (Minutes)",
+          "s (Seconds)",
+          "ms (Milliseconds)",
+          "micros (Microseconds)",
+          "nanos (Nanoseconds)"
+        ]
+      },
       "ts":{
         "type":"boolean",
         "description":"Set to false to disable timestamping",

rest-api-spec/src/main/resources/rest-api-spec/api/cat.indices.json

@@ -78,6 +78,19 @@
         "type":"list",
         "description":"Comma-separated list of column names or column aliases to sort by"
       },
+      "time":{
+        "type":"enum",
+        "description":"The unit in which to display time values",
+        "options":[
+          "d (Days)",
+          "h (Hours)",
+          "m (Minutes)",
+          "s (Seconds)",
+          "ms (Milliseconds)",
+          "micros (Microseconds)",
+          "nanos (Nanoseconds)"
+        ]
+      },
       "v":{
         "type":"boolean",
         "description":"Verbose mode. Display column headers",

rest-api-spec/src/main/resources/rest-api-spec/api/cat.nodes.json

@@ -16,6 +16,23 @@
       ]
     },
     "params":{
+      "bytes":{
+        "type":"enum",
+        "description":"The unit in which to display byte values",
+        "options":[
+          "b",
+          "k",
+          "kb",
+          "m",
+          "mb",
+          "g",
+          "gb",
+          "t",
+          "tb",
+          "p",
+          "pb"
+        ]
+      },
       "format":{
         "type":"string",
         "description":"a short version of the Accept header, e.g. json, yaml"
@@ -45,6 +62,19 @@
         "type":"list",
         "description":"Comma-separated list of column names or column aliases to sort by"
       },
+      "time":{
+        "type":"enum",
+        "description":"The unit in which to display time values",
+        "options":[
+          "d (Days)",
+          "h (Hours)",
+          "m (Minutes)",
+          "s (Seconds)",
+          "ms (Milliseconds)",
+          "micros (Microseconds)",
+          "nanos (Nanoseconds)"
+        ]
+      },
       "v":{
         "type":"boolean",
         "description":"Verbose mode. Display column headers",

rest-api-spec/src/main/resources/rest-api-spec/api/cat.pending_tasks.json

@@ -41,6 +41,19 @@
         "type":"list",
         "description":"Comma-separated list of column names or column aliases to sort by"
       },
+      "time":{
+        "type":"enum",
+        "description":"The unit in which to display time values",
+        "options":[
+          "d (Days)",
+          "h (Hours)",
+          "m (Minutes)",
+          "s (Seconds)",
+          "ms (Milliseconds)",
+          "micros (Microseconds)",
+          "nanos (Nanoseconds)"
+        ]
+      },
       "v":{
         "type":"boolean",
         "description":"Verbose mode. Display column headers",

rest-api-spec/src/main/resources/rest-api-spec/api/cat.recovery.json

@@ -80,6 +80,19 @@
         "type":"list",
         "description":"Comma-separated list of column names or column aliases to sort by"
       },
+      "time":{
+        "type":"enum",
+        "description":"The unit in which to display time values",
+        "options":[
+          "d (Days)",
+          "h (Hours)",
+          "m (Minutes)",
+          "s (Seconds)",
+          "ms (Milliseconds)",
+          "micros (Microseconds)",
+          "nanos (Nanoseconds)"
+        ]
+      },
       "v":{
         "type":"boolean",
         "description":"Verbose mode. Display column headers",

rest-api-spec/src/main/resources/rest-api-spec/api/cat.shards.json

@@ -70,6 +70,19 @@
         "type":"list",
         "description":"Comma-separated list of column names or column aliases to sort by"
       },
+      "time":{
+        "type":"enum",
+        "description":"The unit in which to display time values",
+        "options":[
+          "d (Days)",
+          "h (Hours)",
+          "m (Minutes)",
+          "s (Seconds)",
+          "ms (Milliseconds)",
+          "micros (Microseconds)",
+          "nanos (Nanoseconds)"
+        ]
+      },
       "v":{
         "type":"boolean",
         "description":"Verbose mode. Display column headers",

rest-api-spec/src/main/resources/rest-api-spec/api/cat.snapshots.json

@@ -54,6 +54,19 @@
         "type":"list",
         "description":"Comma-separated list of column names or column aliases to sort by"
       },
+      "time":{
+        "type":"enum",
+        "description":"The unit in which to display time values",
+        "options":[
+          "d (Days)",
+          "h (Hours)",
+          "m (Minutes)",
+          "s (Seconds)",
+          "ms (Milliseconds)",
+          "micros (Microseconds)",
+          "nanos (Nanoseconds)"
+        ]
+      },
       "v":{
         "type":"boolean",
         "description":"Verbose mode. Display column headers",

rest-api-spec/src/main/resources/rest-api-spec/api/cat.tasks.json

@@ -49,6 +49,19 @@
         "type":"list",
         "description":"Comma-separated list of column names or column aliases to sort by"
       },
+      "time":{
+        "type":"enum",
+        "description":"The unit in which to display time values",
+        "options":[
+          "d (Days)",
+          "h (Hours)",
+          "m (Minutes)",
+          "s (Seconds)",
+          "ms (Milliseconds)",
+          "micros (Microseconds)",
+          "nanos (Nanoseconds)"
+        ]
+      },
       "v":{
         "type":"boolean",
         "description":"Verbose mode. Display column headers",