CBG-4312 improve metrics documentation

- remove /_metrics endpoint, which does not need public API
  documentation, as it never should have been implemented
- change copy to match public docs for description
- add links to upstream files

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)

docs/api/components/schemas.yaml

@@ -166,8 +166,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)
@@ -30,15 +34,17 @@ servers:
 paths:
   /_ping:
     $ref: ./paths/common/_ping.yaml
-  /_metrics:
-    $ref: ./paths/metric/metrics.yaml
   /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'

docs/api/paths/metric/_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,9 +18,13 @@ 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:
           schema:

docs/api/paths/metric/metrics.yaml

@@ -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/public.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)