CBG-4604 document missing run states

- update online/offline endpoints to discourage use

Author: torcolvin

docs/api/components/schemas.yaml

@@ -2904,14 +2904,8 @@ Status:
             description: The server unique identifier.
             type: string
           state:
-            description: Whether the database is online or offline.
-            type: string
-            enum:
-              - Online
-              - Offline
-              - Starting
-              - Stopping
-              - Resyncing
+            allOf: # use allOf to prevent DatabaseState from showing as the type in the display
+              - $ref: '#/DatabaseState'
           replication_status:
             type: array
             items:
@@ -3017,14 +3011,8 @@ CollectionNames:
         type: string
         description: The Couchbase Server backing bucket for the database.
       state:
-        description: The database state.
-        type: string
-        enum:
-          - Online
-          - Offline
-          - Starting
-          - Stopping
-          - Resyncing
+        allOf: # use allOf to prevent DatabaseState from showing as the type in the display
+          - $ref: '#/DatabaseState'
       require_resync:
         description: Indicates whether the database requires resync before it can be brought online.
         type: boolean
@@ -3075,3 +3063,18 @@ doc_access_spans:
             entries:
               type: array
               description: Start sequence to end sequence. If the channel is currently granted, the end sequence will be zero.
+DatabaseState:
+  description: The state of the database.
+  type: string
+  enum:
+    - Online
+    - Offline
+    - Starting
+    - Stopping
+    - Resyncing
+  x-enumDescriptions:
+    Online: The database is online and available for use.
+    Offline: The database is offline, resync and other offline only endpoints are allowed.
+    Starting: The database is in the process of going online.
+    Stopping: The database is no longer accepting connections and is being taken offline or deleted.
+    Resyncing: The database is offline and performing a resync operation.

docs/api/paths/admin/db-.yaml

@@ -57,11 +57,8 @@ get:
                 type: number
                 default: 0
               state:
-                description: 'The database state. Change using the `/{db}/_offline` and `/{db}/_online` endpoints.'
-                type: string
-                enum:
-                  - Online
-                  - Offline
+                allOf: # use allOf to prevent DatabaseState from showing as the type in the display
+                  - $ref: ../../components/schemas.yaml#/DatabaseState
               server_uuid:
                 description: Unique server identifier.
                 type: string

docs/api/paths/admin/db-_offline.yaml

@@ -10,7 +10,9 @@ parameters:
 post:
   summary: Take the database offline
   description: |-
-    This will take the database offline meaning actions can be taken without disrupting current operations ungracefully or having the restart the Sync Gateway instance.
+    If using persistent config, call [POST /{db}/_config](#operation/post_db-_config) with `{"offline": true}` to set the database to offline.
+
+    This will take the database offline on this node only. Actions can be taken without disrupting current operations ungracefully or having the restart the Sync Gateway instance.
 
     This will not take the backing Couchbase Server bucket offline.
 

docs/api/paths/admin/db-_online.yaml

@@ -10,7 +10,9 @@ parameters:
 post:
   summary: Bring the database online
   description: |-
-    This will bring the database online so the Public and full Admin REST API requests can be served.
+    This will bring the database online on this node only so the Public and full Admin REST API requests can be served.
+
+    If using persistent config, call [POST /{db}/_config](#operation/post_db-_config) with `{"offline": false}` to set the database to online.
 
     Bringing a database online will:
     * Close the database connection to the backing Couchbase Server bucket.

docs/api/paths/admin/db-_resync.yaml

@@ -34,7 +34,7 @@ post:
 
     Generally, a resync operation might be wanted when the sync function has been modified in such a way that the channel or access mappings for any existing documents would change as a result.
 
-    A resync operation cannot be run if the database is online. The database can be taken offline by calling the `POST /{db}/_offline` endpoint.
+    A resync operation cannot be run if the database is online. The database can be taken offline by calling [POST /{db}/_config](#operation/post_db-_config) with `{"offline": true}` to set the database to offline.
 
     The `requireUser()` and `requireRole()` calls in the sync function will always return `true`.
 

docs/api/paths/public/db-.yaml

@@ -52,11 +52,8 @@ get:
                 type: number
                 default: 0
               state:
-                description: 'The database state. Change using the `/{db}/_offline` and `/{db}/_online` endpoints.'
-                type: string
-                enum:
-                  - Online
-                  - Offline
+                allOf: # use allOf to prevent DatabaseState from showing as the type in the display
+                  - $ref: ../../components/schemas.yaml#/DatabaseState
               server_uuid:
                 description: Unique server identifier.
                 type: string