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

jrodewig · web-flow · commit 04451d0f8195 · 2019-10-10T12:03:47.000-04:00
diff --git a/docs/reference/cat/alias.asciidoc b/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]]
diff --git a/docs/reference/cat/allocation.asciidoc b/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}
 
diff --git a/docs/reference/cat/count.asciidoc b/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}
diff --git a/docs/reference/cat/fielddata.asciidoc b/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}
diff --git a/docs/reference/cat/health.asciidoc b/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
diff --git a/docs/reference/cat/indices.asciidoc b/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]
 
 
diff --git a/docs/reference/cat/nodes.asciidoc b/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]
 
 
diff --git a/docs/reference/cat/pending_tasks.asciidoc b/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]
 
 
diff --git a/docs/reference/cat/recovery.asciidoc b/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]
 
 
diff --git a/docs/reference/cat/segments.asciidoc b/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}
diff --git a/docs/reference/cat/shards.asciidoc b/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]
 
 
diff --git a/docs/reference/cat/snapshots.asciidoc b/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]
 
 
diff --git a/docs/reference/cat/tasks.asciidoc b/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]
diff --git a/docs/reference/cat/templates.asciidoc b/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}
diff --git a/docs/reference/cat/thread_pool.asciidoc b/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}
 
diff --git a/docs/reference/rest-api/common-parms.asciidoc b/docs/reference/rest-api/common-parms.asciidoc
@@ -438,11 +438,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
@@ -688,6 +683,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[]
diff --git a/rest-api-spec/src/main/resources/rest-api-spec/api/cat.health.json b/rest-api-spec/src/main/resources/rest-api-spec/api/cat.health.json
@@ -33,6 +33,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",
diff --git a/rest-api-spec/src/main/resources/rest-api-spec/api/cat.indices.json b/rest-api-spec/src/main/resources/rest-api-spec/api/cat.indices.json
@@ -53,6 +53,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",
diff --git a/rest-api-spec/src/main/resources/rest-api-spec/api/cat.nodes.json b/rest-api-spec/src/main/resources/rest-api-spec/api/cat.nodes.json
@@ -12,6 +12,23 @@
           "type" : "string",
           "description" : "a short version of the Accept header, e.g. json, yaml"
         },
+        "bytes":{
+          "type":"enum",
+          "description":"The unit in which to display byte values",
+          "options":[
+            "b",
+            "k",
+            "kb",
+            "m",
+            "mb",
+            "g",
+            "gb",
+            "t",
+            "tb",
+            "p",
+            "pb"
+          ]
+        },
         "full_id": {
           "type" : "boolean",
           "description" : "Return the full node ID instead of the shortened version (default: false)"
@@ -37,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",
diff --git a/rest-api-spec/src/main/resources/rest-api-spec/api/cat.pending_tasks.json b/rest-api-spec/src/main/resources/rest-api-spec/api/cat.pending_tasks.json
@@ -33,6 +33,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",
diff --git a/rest-api-spec/src/main/resources/rest-api-spec/api/cat.recovery.json b/rest-api-spec/src/main/resources/rest-api-spec/api/cat.recovery.json
@@ -52,6 +52,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",
diff --git a/rest-api-spec/src/main/resources/rest-api-spec/api/cat.shards.json b/rest-api-spec/src/main/resources/rest-api-spec/api/cat.shards.json
@@ -42,6 +42,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",
diff --git a/rest-api-spec/src/main/resources/rest-api-spec/api/cat.snapshots.json b/rest-api-spec/src/main/resources/rest-api-spec/api/cat.snapshots.json
@@ -40,6 +40,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",
diff --git a/rest-api-spec/src/main/resources/rest-api-spec/api/cat.tasks.json b/rest-api-spec/src/main/resources/rest-api-spec/api/cat.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",
