From 95d3a8e8add527788525cdcd744bef2972613713 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Istv=C3=A1n=20Zolt=C3=A1n=20Szab=C3=B3?=
 <istvan.szabo@elastic.co>
Date: Wed, 7 Aug 2019 16:46:39 +0200
Subject: [PATCH]  [DOCS] Reformats cluster stats API and expands common params
 (#45270)

Co-Authored-By: James Rodewig <james.rodewig@elastic.co>
---
 docs/reference/cluster/stats.asciidoc         | 44 ++++++++++++++++---
 docs/reference/rest-api/common-parms.asciidoc |  6 +++
 2 files changed, 45 insertions(+), 5 deletions(-)

diff --git a/docs/reference/cluster/stats.asciidoc b/docs/reference/cluster/stats.asciidoc
index e51c66880f6..42fa6af398e 100644
--- a/docs/reference/cluster/stats.asciidoc
+++ b/docs/reference/cluster/stats.asciidoc
@@ -1,10 +1,43 @@
 [[cluster-stats]]
 === Cluster Stats
 
-The Cluster Stats API allows to retrieve statistics from a cluster wide perspective.
-The API returns basic index metrics (shard numbers, store size, memory usage) and
-information about the current nodes that form the cluster (number, roles, os, jvm
-versions, memory usage, cpu and installed plugins).
+Returns cluster statistics.
+
+
+[[cluster-stats-api-request]]
+==== {api-request-title}
+
+`GET /_cluster/stats` +
+
+`GET /_cluster/stats/nodes/{node_id}`
+
+
+[[cluster-stats-api-desc]]
+==== {api-description-title}
+
+The Cluster Stats API allows to retrieve statistics from a cluster wide 
+perspective. The API returns basic index metrics (shard numbers, store size, 
+memory usage) and information about the current nodes that form the cluster 
+(number, roles, os, jvm versions, memory usage, cpu and installed plugins).
+
+
+[[cluster-stats-api-path-params]]
+==== {api-path-parms-title}
+
+
+include::{docdir}/rest-api/common-parms.asciidoc[tag=node-id]
+
+
+[[cluster-stats-api-query-params]]
+==== {api-query-parms-title}
+
+include::{docdir}/rest-api/common-parms.asciidoc[tag=flat-settings]
+
+include::{docdir}/rest-api/common-parms.asciidoc[tag=timeoutparms]
+
+
+[[cluster-stats-api-example]]
+==== {api-examples-title}
 
 [source,js]
 --------------------------------------------------
@@ -13,7 +46,8 @@ GET /_cluster/stats?human&pretty
 // CONSOLE
 // TEST[setup:twitter]
 
-Will return, for example:
+The API returns the following response:
+
 ["source","js",subs="attributes,callouts"]
 --------------------------------------------------
 {
diff --git a/docs/reference/rest-api/common-parms.asciidoc b/docs/reference/rest-api/common-parms.asciidoc
index 7169b624107..84e4c57e99f 100644
--- a/docs/reference/rest-api/common-parms.asciidoc
+++ b/docs/reference/rest-api/common-parms.asciidoc
@@ -9,6 +9,12 @@ tag::cat-h[]
 (Optional, string) Comma-separated list of column names to display.
 end::cat-h[]
 
+tag::flat-settings[]
+`flat_settings`::
+(Optional, boolean) If `true`, returns settings in flat format. Defaults to 
+`false`.
+end::flat-settings[]
+
 tag::help[]
 `help`::
 (Optional, boolean) If `true`, the response returns help information. Defaults