CBG-4312 improve metrics documentation (#7309)

Author: torcolvin

docs/api/admin.yaml

@@ -8,8 +8,11 @@
 
 openapi: 3.0.3
 info:
-  title: Sync Gateway
-  description: Sync Gateway manages access and synchronization between Couchbase Lite and Couchbase Server
+  title: Sync Gateway Admin REST API
+  description: |-
+    # Introduction
+
+    The Sync Gateway Admin REST API is used to administer user accounts and roles, and to run administrative tasks in superuser mode.
   version: '3.3'
   license:
     name: Business Source License 1.1 (BSL)
@@ -129,7 +132,8 @@ paths:
   '/{keyspace}/':
     $ref: './paths/admin/keyspace-.yaml'
   /_expvar:
-    $ref: ./paths/admin/_expvar.yaml
+    # use the same path as for metrics
+    $ref: ./paths/metric/_expvar.yaml
   /:
     $ref: ./paths/admin/-.yaml
   /_ping:
@@ -207,5 +211,5 @@ tags:
   - name: Unsupported
     description: Endpoints that are not supported by Sync Gateway
 externalDocs:
-  description: Sync Gateway Quickstart | Couchbase Docs
-  url: 'https://docs.couchbase.com/sync-gateway/current/index.html'
+  description: ⬆️ Admin REST API Overview
+  url: rest-api-admin.html

docs/api/components/schemas.yaml

@@ -169,8 +169,9 @@ ExpVars:
                   description: "The total uptime."
         per_db:
           description: |-
-            This array contains stats for all databases declared in the config file -- see the [Sync Gateway Statistics Schema](./../stats-monitoring.html) for more details on the metrics collected and reported by Sync Gateway.
-            The statistics for each {$db_name} database are grouped into:
+            This array contains stats for all databases declared in the config file — see [View Statistics and Metrics](stats-monitoring.html) for more details on the metrics collected and reported by Sync Gateway.
+
+            The statistics for each database are grouped into:
             - cache related statistics
             - collections statistics
             - cbl_replication_push

docs/api/metric.yaml

@@ -8,8 +8,12 @@
 
 openapi: 3.0.3
 info:
-  title: Sync Gateway
-  description: Sync Gateway manages access and synchronization between Couchbase Lite and Couchbase Server
+  title: Sync Gateway Metrics REST API
+  description: |-
+    # Introduction
+
+    Sync Gateway manages access and synchronization between Couchbase Lite and Couchbase Server.
+    The Sync Gateway Metrics REST API returns Sync Gateway metrics, in JSON or Prometheus-compatible formats, for performance monitoring and diagnostic purposes.
   version: '3.3'
   license:
     name: Business Source License 1.1 (BSL)
@@ -32,13 +36,18 @@ paths:
     $ref: ./paths/common/_ping.yaml
   /_metrics:
     $ref: ./paths/metric/metrics.yaml
+    x-internal: true
   /metrics:
     $ref: ./paths/metric/metrics.yaml
   /_expvar:
     $ref: ./paths/metric/_expvar.yaml
 tags:
   - name: Prometheus
     description: Endpoints for use with Prometheus
+  - name: JSON
+    description: Endpoints for use with JSON metrics
+  - name: Server
+    description: Endpoints for managing the REST API
 externalDocs:
-  description: Sync Gateway Quickstart | Couchbase Docs
-  url: 'https://docs.couchbase.com/sync-gateway/current/index.html'
+  description: ⬆️ Metrics REST API Overview
+  url: rest-api-metrics.html

docs/api/paths/admin/_expvar.yaml

@@ -7,7 +7,7 @@
 # software will be governed by the Apache License, Version 2.0, included in
 # the file licenses/APL2.txt.
 get:
-  summary: Get all Sync Gateway statistics
+  summary: Get all Sync Gateway statistics in JSON format
   description: |-
     This returns a snapshot of all metrics in Sync Gateway for debugging and monitoring purposes.
 
@@ -18,11 +18,15 @@ get:
     * Sync Gateway Architect
     * Sync Gateway Dev Ops
     * External Stats Reader
+  tags:
+    - JSON
   responses:
     '200':
-      description: Returned statistics
+      description: |-
+          Successfully returned statistics.
+          For details, see [JSON Metrics](stats-monitoring-json.html).
       content:
-        application/javascript:
+        application/json:
           schema:
             $ref: ../../components/schemas.yaml#/ExpVars
   operationId: get__expvar

docs/api/paths/metric/_expvar.yaml

@@ -6,7 +6,7 @@
 # software will be governed by the Apache License, Version 2.0, included in
 # the file licenses/APL2.txt.
 get:
-  summary: Debugging/monitoring runtime stats in Prometheus Exposition format
+  summary: Get debugging and monitoring runtime stats in Prometheus Exposition format
   description: |-
     Returns Sync Gateway statistics and other runtime variables in Prometheus Exposition format.
 
@@ -17,11 +17,9 @@ get:
     * External Stats Reader
   responses:
     '200':
-      description: Successfully returned stats
-      content:
-        text/plain:
-          schema:
-            type: string
+      description: |-
+          Successfully returned statistics.
+          For details, see [Prometheus Metrics](stats-monitoring-prometheus.html).
   tags:
     - Prometheus
   operationId: get_metrics

docs/api/paths/metric/metrics.yaml

@@ -8,8 +8,12 @@
 
 openapi: 3.0.3
 info:
-  title: Sync Gateway
-  description: Sync Gateway manages access and synchronization between Couchbase Lite and Couchbase Server
+  title: Sync Gateway Public REST API
+  description: |-
+    # Introduction
+
+    Sync Gateway manages access and synchronization between Couchbase Lite and Couchbase Server.
+    The Sync Gateway Public REST API is used for client replication.
   version: '3.3'
   license:
     name: Business Source License 1.1 (BSL)
@@ -108,5 +112,5 @@ tags:
     description: Endpoints that are not supported by Sync Gateway
     x-capella: false
 externalDocs:
-  description: Sync Gateway Quickstart | Couchbase Docs
-  url: 'https://docs.couchbase.com/sync-gateway/current/index.html'
+  description: ⬆️ Public REST API Overview
+  url: rest-api.html