[TEST] Add missing docs and tests for '_cat/segments'

The '_cat/segments' api was missing docs and a rest test which are added here.

Closes #5856

docs/reference/cat.asciidoc

@@ -120,3 +120,4 @@ include::cat/thread_pool.asciidoc[]
 
 include::cat/shards.asciidoc[]
 
+include::cat/segments.asciidoc[]

docs/reference/cat/segments.asciidoc

@@ -0,0 +1,71 @@
+[[cat-segments]]
+== cat segments
+
+The `segments` command provides low level information about the segments
+in the shards of an index. It provides information similar to the
+link:indices-segments.html[_segments] endpoint.
+
+[source,shell]
+--------------------------------------------------
+% curl 'http://localhost:9200/_cat/segments?v'
+index shard prirep ip            segment generation docs.count [...]
+test  4     p      192.168.2.105 _0               0          1
+test1 2     p      192.168.2.105 _0               0          1
+test1 3     p      192.168.2.105 _2               2          1
+--------------------------------------------------
+
+[source,shell]
+--------------------------------------------------
+[...] docs.deleted  size size.memory committed searchable version compound
+                 0 2.9kb        7818 false     true       4.10.2  true
+                 0 2.9kb        7818 false     true       4.10.2  true
+                 0 2.9kb        7818 false     true       4.10.2  true
+--------------------------------------------------
+
+The output shows information about index names and shard numbers in the first
+two columns.
+
+If you only want to get information about segments in one particular index,
+you can add the index name in the URL, for example `/_cat/segments/test`. Also,
+several indexes can be queried like `/_cat/segments/test,test1`
+
+
+The following columns provide additional monitoring information:
+
+prirep::        Whether this segment belongs to a primary or replica shard.
+
+ip::            The ip address of the segments shard.
+
+segment::       A segment name, derived from the segment generation. The name
+                is internally used to generate the file names in the directory
+                of the shard this segment belongs to.
+
+generation::    The generation number is incremented with each segment that is written.
+                The name of the segment is derived from this generation number.
+
+docs.count::    The number of non-deleted documents that are stored in this segment.
+
+docs.deleted::  The number of deleted documents that are stored in this segment.
+                It is perfectly fine if this number is greater than 0, space is
+                going to be reclaimed when this segment gets merged.
+
+size::          The amount of disk space that this segment uses.
+
+size.memory::   Segments store some data into memory in order to be searchable efficiently.
+                This column shows the number of bytes in memory that are used.
+
+committed::     Whether the segment has been sync'ed on disk. Segments that are
+                committed would survive a hard reboot. No need to worry in case
+                of false, the data from uncommitted segments is also stored in
+                the transaction log so that Elasticsearch is able to replay
+                changes on the next start.
+
+searchable::    True if the segment is searchable. A value of false would most
+                likely mean that the segment has been written to disk but no
+                refresh occurred since then to make it searchable.
+
+version::       The version of Lucene that has been used to write this segment.
+
+compound::      Whether the segment is stored in a compound file. When true, this
+                means that Lucene merged all files from the segment in a single
+                one in order to save file descriptors.

rest-api-spec/api/cat.segments.json

@@ -0,0 +1,33 @@
+{
+  "cat.segments": {
+    "documentation": "http://www.elasticsearch.org/guide/en/elasticsearch/reference/master/cat-segments.html",
+    "methods": ["GET"],
+    "url": {
+      "path": "/_cat/segments",
+      "paths": ["/_cat/segments", "/_cat/segments/{index}"],
+      "parts": {
+        "index": {
+          "type" : "list",
+          "description": "A comma-separated list of index names to limit the returned information"
+        }
+      },
+      "params": {
+        "h": {
+            "type": "list",
+            "description" : "Comma-separated list of column names to display"
+        },
+        "help": {
+          "type": "boolean",
+          "description": "Return help information",
+          "default": false
+        },
+        "v": {
+          "type": "boolean",
+          "description": "Verbose mode. Display column headers",
+          "default": true
+        }
+      }
+    },
+    "body": null
+  }
+}

rest-api-spec/test/cat.segments/10_basic.yaml

@@ -0,0 +1,87 @@
+---
+"Help":
+  - do:
+      cat.segments:
+        help: true
+
+  - match:
+      $body: |
+               /^   index        .+   \n
+                    shard        .+   \n
+                    prirep       .+   \n
+                    ip           .+   \n
+                    segment      .+   \n
+                    generation   .+   \n
+                    docs.count   .+   \n
+                    docs.deleted .+   \n
+                    size         .+   \n
+                    size.memory  .+   \n
+                    committed    .+   \n
+                    searchable   .+   \n
+                    version      .+   \n
+                    compound     .+   \n
+               $/
+---
+"Test cat segments output":
+
+  - do:
+      indices.create:
+        index: index1
+        body:
+          settings:
+            number_of_shards: "3"
+            number_of_replicas: "0"
+  - do:
+      index:
+        index: index1
+        type: type
+        body: { foo: bar }
+        refresh: true
+  - do:
+       cluster.health:
+         wait_for_status: yellow
+  - do:
+      cat.segments:
+        v: false
+  - match:
+      $body: |
+                 /^(index1 \s+ \d \s+ (p|r) \s+ \d{1,3}\.\d{1,3}\.\d{1,3}\.\d{1,3} \s+ _\d (\s\d){3} \s+
+                 (\d+|\d+[.]\d+)(kb|b) \s+ \d+ (\s+ (false|true)){2} \s+  \d+\.\d+\.\d+ \s+ (false|true) \s? \n?)$/
+
+  - do:
+      indices.create:
+        index: index2
+        body:
+          settings:
+            number_of_shards: "3"
+            number_of_replicas: "0"
+  - do:
+       cluster.health:
+         wait_for_status: yellow
+         wait_for_relocating_shards: 0
+
+  - do:
+      index:
+        index: index2
+        type: type
+        body: { foo: bar }
+        refresh: true
+  - do:
+       cluster.health:
+         wait_for_status: yellow
+
+
+  - do:
+      cat.segments:
+        v: false
+  - match:
+      $body: |
+                  /^(index(1|2) .+ \n?){2}$/
+
+  - do:
+      cat.segments:
+        index: index2
+        v: false
+  - match:
+      $body: |
+                  /^(index2 .+ \n?)$/