CBG-4604 document missing run states

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.
+    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.
+
+    If using persistent config, call [POST /{db}/_config](#operation/post_db-_config) with `{"offline": true}` to set the database to offline.
 
     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