[3.2.5 backport] openapi docs improvements (#7517)

Co-authored-by: Simon Dew <[email protected]>

Author: torcolvin

docs/api/admin.yaml

@@ -39,6 +39,10 @@ paths:
     $ref: './paths/admin/keyspace-_raw-docid.yaml'
   '/{keyspace}/_revtree/{docid}':
     $ref: './paths/admin/keyspace-_revtree-docid.yaml'
+  '/{db}/':
+    $ref: './paths/admin/db-.yaml'
+  /_all_dbs:
+    $ref: ./paths/admin/_all_dbs.yaml
   '/{db}/_user/':
     $ref: './paths/admin/db-_user-.yaml'
   '/{db}/_user/{name}':
@@ -59,8 +63,6 @@ paths:
     $ref: './paths/admin/db-_replicationStatus-.yaml'
   '/{db}/_replicationStatus/{replicationid}':
     $ref: './paths/admin/db-_replicationStatus-replicationid.yaml'
-  /_logging:
-    $ref: ./paths/admin/_logging.yaml
   '/_profile/{profilename}':
     $ref: './paths/admin/_profile-profilename.yaml'
   /_profile:
@@ -123,35 +125,22 @@ paths:
     $ref: './paths/admin/keyspace-_dumpchannel-channel.yaml'
   '/{db}/_repair':
     $ref: './paths/admin/db-_repair.yaml'
-  /_all_dbs:
-    $ref: ./paths/admin/_all_dbs.yaml
   '/{db}/_compact':
     $ref: './paths/admin/db-_compact.yaml'
-  '/{db}/':
-    $ref: './paths/admin/db-.yaml'
   '/{keyspace}/':
     $ref: './paths/admin/keyspace-.yaml'
   /_expvar:
-    # use the same path as for metrics
-    $ref: ./paths/metric/_expvar.yaml
+    $ref: ./paths/admin/_expvar.yaml
   /:
     $ref: ./paths/admin/-.yaml
   /_ping:
     $ref: ./paths/common/_ping.yaml
-  '/{keyspace}/_all_docs':
-    $ref: './paths/admin/keyspace-_all_docs.yaml'
-  '/{keyspace}/_bulk_docs':
-    $ref: './paths/admin/keyspace-_bulk_docs.yaml'
-  '/{keyspace}/_bulk_get':
-    $ref: './paths/admin/keyspace-_bulk_get.yaml'
   '/{keyspace}/_changes':
     $ref: './paths/admin/keyspace-_changes.yaml'
   '/{db}/_design/{ddoc}':
     $ref: './paths/admin/db-_design-ddoc.yaml'
   '/{db}/_design/{ddoc}/_view/{view}':
     $ref: './paths/admin/db-_design-ddoc-_view-view.yaml'
-  '/{db}/_ensure_full_commit':
-    $ref: './paths/admin/db-_ensure_full_commit.yaml'
   '/{keyspace}/_revs_diff':
     $ref: './paths/admin/keyspace-_revs_diff.yaml'
   '/{keyspace}/_local/{docid}':
@@ -160,10 +149,12 @@ paths:
     $ref: './paths/admin/keyspace-docid.yaml'
   '/{keyspace}/{docid}/{attach}':
     $ref: './paths/admin/keyspace-docid-attach.yaml'
-  '/{db}/_facebook':
-    $ref: './paths/admin/db-_facebook.yaml'
-  '/{db}/_google':
-    $ref: './paths/admin/db-_google.yaml'
+  '/{keyspace}/_all_docs':
+    $ref: './paths/admin/keyspace-_all_docs.yaml'
+  '/{keyspace}/_bulk_docs':
+    $ref: './paths/admin/keyspace-_bulk_docs.yaml'
+  '/{keyspace}/_bulk_get':
+    $ref: './paths/admin/keyspace-_bulk_get.yaml'
   '/{db}/_oidc':
     $ref: './paths/admin/db-_oidc.yaml'
   '/{db}/_oidc_challenge':
@@ -173,18 +164,26 @@ paths:
   '/{db}/_oidc_refresh':
     $ref: './paths/admin/db-_oidc_refresh.yaml'
   '/{db}/_oidc_testing/.well-known/openid-configuration':
-    $ref: './paths/admin/db-_oidc_testing-.well-known-openid-configuration.yaml'
+    $ref: './paths/common/db-_oidc_testing-.well-known-openid-configuration.yaml'
   '/{db}/_oidc_testing/authorize':
-    $ref: './paths/admin/db-_oidc_testing-authorize.yaml'
+    $ref: './paths/common/db-_oidc_testing-authorize.yaml'
   '/{db}/_oidc_testing/token':
-    $ref: './paths/admin/db-_oidc_testing-token.yaml'
+    $ref: './paths/common/db-_oidc_testing-token.yaml'
   '/{db}/_oidc_testing/certs':
-    $ref: './paths/admin/db-_oidc_testing-certs.yaml'
+    $ref: './paths/common/db-_oidc_testing-certs.yaml'
   '/{db}/_oidc_testing/authenticate':
-    $ref: './paths/admin/db-_oidc_testing-authenticate.yaml'
+    $ref: './paths/common/db-_oidc_testing-authenticate.yaml'
   '/{db}/_blipsync':
     $ref: './paths/admin/db-_blipsync.yaml'
-
+  # deprecated endpoints, put at the end to show up at the bottom
+  '/{db}/_facebook':
+    $ref: './paths/admin/db-_facebook.yaml'
+  '/{db}/_google':
+    $ref: './paths/admin/db-_google.yaml'
+  '/{db}/_ensure_full_commit':
+    $ref: './paths/common/db-_ensure_full_commit.yaml'
+  /_logging:
+    $ref: ./paths/admin/_logging.yaml
 tags:
   - name: Authentication
     description: Manage authentication

docs/api/components/responses.yaml

@@ -192,3 +192,12 @@ user_access_span_response:
     application/json:
       schema:
         $ref: ./schemas.yaml#/doc_access_spans
+expvar_reponses:
+  '200':
+    description: |-
+        Successfully returned statistics.
+        For details, see [JSON Metrics](stats-monitoring-json.html).
+    content:
+      application/json:
+        schema:
+          $ref: ./schemas.yaml#/ExpVars