diff --git a/docs/api/admin.yaml b/docs/api/admin.yaml index 7136a22fdb..338f76b780 100644 --- a/docs/api/admin.yaml +++ b/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 diff --git a/docs/api/components/schemas.yaml b/docs/api/components/schemas.yaml index 2f9560165a..99ff876a04 100644 --- a/docs/api/components/schemas.yaml +++ b/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 diff --git a/docs/api/metric.yaml b/docs/api/metric.yaml index 990922052f..07091722dc 100644 --- a/docs/api/metric.yaml +++ b/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,6 +36,7 @@ paths: $ref: ./paths/common/_ping.yaml /_metrics: $ref: ./paths/metric/metrics.yaml + x-internal: true /metrics: $ref: ./paths/metric/metrics.yaml /_expvar: @@ -39,6 +44,10 @@ paths: 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 diff --git a/docs/api/paths/admin/_expvar.yaml b/docs/api/paths/admin/_expvar.yaml deleted file mode 100644 index c3e53f154c..0000000000 --- a/docs/api/paths/admin/_expvar.yaml +++ /dev/null @@ -1,29 +0,0 @@ -# Copyright 2022-Present Couchbase, Inc. -# -# Use of this software is governed by the Business Source License included -# in the file licenses/BSL-Couchbase.txt. As of the Change Date specified -# in that file, in accordance with the Business Source License, use of this -# 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 - description: |- - This returns a snapshot of all metrics in Sync Gateway for debugging and monitoring purposes. - - This includes per database stats, replication stats, and server stats. - - Required Sync Gateway RBAC roles: - - * Sync Gateway Architect - * Sync Gateway Dev Ops - * External Stats Reader - responses: - '200': - description: Returned statistics - content: - application/javascript: - schema: - $ref: ../../components/schemas.yaml#/ExpVars - tags: - - Metrics - operationId: get__expvar diff --git a/docs/api/paths/metric/_expvar.yaml b/docs/api/paths/metric/_expvar.yaml index b57d9adcfe..d1eb46e7dd 100644 --- a/docs/api/paths/metric/_expvar.yaml +++ b/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,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 diff --git a/docs/api/paths/metric/metrics.yaml b/docs/api/paths/metric/metrics.yaml index 729260751d..e1f06dc580 100644 --- a/docs/api/paths/metric/metrics.yaml +++ b/docs/api/paths/metric/metrics.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 diff --git a/docs/api/public.yaml b/docs/api/public.yaml index 213a10e90e..3fee9b4e3a 100644 --- a/docs/api/public.yaml +++ b/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) @@ -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