HTTP API: Add missing defaults/enums, fix mistakes (#718)

* HTTP API: Add some missing defaults/enums

* More defaults, formatting, rev parameter in Gharial vertex/edge ops, mention startup options, add missing slowStreamingQueryThreshold option

* Named graphs: Remove docs for superfluous rev query param, some rewording

* Rewording, missing defaults

* Index API: Backport changes to 3.11

* Apply rewording to JS API docs

* Rework concept page about key generators, add padded and uuid

* Users: passwd is not mandatory, PUT resets access levels

* Fix shard IDs example and missing response description

details parameter would require polymorphic response description (array or object) but we cannot render this at the moment

* maxTransactionSize not available in 3.11

* CSS: Make the version selector gray instead of green

* Unify release notes

* Finish up improvements to OpenAPI descriptions

Missing defaults, add uniqueItems property for indexes, fix type/structure mistakes, reword some descriptions

Certain endpoints like for transactions would require multiple types (string or array of strings), but we cannot render that yet

* Review feedback

* Apply to 3.11

* [skip ci] Automatic commit of generated files from CircleCI

Author: Simran-B

site/content/3.11/concepts/data-structure/collections.md

@@ -120,29 +120,42 @@ ArangoDB as opaque strings when they store or use them locally.
 
 ## Key generators
 
-ArangoDB allows using key generators for each collection. Key generators
-have the purpose of auto-generating values for the `_key` attribute of a document
-if none was specified by the user. By default, ArangoDB uses the traditional
-key generator. The traditional key generator auto-generates key values that
-are strings with ever-increasing numbers. The increment values it uses are
-non-deterministic.
-
-Contrary, the auto-increment key generator auto-generates deterministic key
-values. Both the start value and the increment value can be defined when the
-collection is created. The default start value is `0` and the default increment
-is `1`, meaning the key values it creates by default are:
-
-1, 2, 3, 4, 5, ...
-
-When creating a collection with the auto-increment key generator and an
-increment of `5`, the generated keys would be:
-
-1, 6, 11, 16, 21, ...
-
-The auto-increment values are increased and handed out on each document insert
-attempt. Even if an insert fails, the auto-increment value is never rolled back.
-That means there may exist gaps in the sequence of assigned auto-increment values
-if inserts fails.
+ArangoDB allows you to use different key generators for each collection.
+Key generators have the purpose of auto-generating a value for the `_key`
+attribute of a document if none was specified by the user.
+
+- **traditional** (default): The `traditional` key generator auto-generates
+  key values that are strings with ever-increasing numbers. The increment values
+  it uses are non-deterministic (e.g. `"137"`, `"140"`, `"141"`, `"145"`, ...).
+
+- **autoincrement**: The `autoincrement` key generator auto-generates
+  deterministic key values. You can define both the start value (`offset`) and
+  the `increment` value when creating the collection. The default start value is
+  `0` and the default increment is `1` (`"1"`, `"2"`, `"3"`, `"4"`, `"5"`, ...).
+  With an `increment` of `5` and `offset` of `2`: `"2"`, `"7"`, `"12"`, `"17"`, `"22"`, ...
+
+  The auto-increment values are increased and handed out on each document insert
+  attempt. Even if an insert fails, the auto-increment value is never rolled back.
+  That means there may exist gaps in the sequence of assigned auto-increment values
+  if inserts fail.
+
+  The `autoincrement` key generator is only supported for collections with a
+  single shard.
+
+- **padded**: The `padded` key generator generates keys of a fixed length
+  (16 bytes) in ascending lexicographical sort order. This is ideal for the
+  RocksDB storage engine, which slightly benefits keys that are inserted in
+  lexicographically ascending order. The sequence of generated keys is not
+  guaranteed to be gap-free (e.g. `"00000000005bb4d9"`, `"00000000005bb4e6"`, ...).
+
+- **uuid**: The `uuid` key generator generates universally unique 128 bit keys,
+  which are stored in hexadecimal human-readable format. The keys produced by
+  this key generator are not lexicographically sorted (e.g.
+  `"04648089-bdeb-4852-b570-f5280f68cf19"`, `"d0f1069c-e38b-4327-8e1e-6bdf7fd33865"`, ...).
+
+If you specify keys for some documents but rely on key generation for other
+documents targeting the same collection, conflicts may occur. You can set
+`allowUserKeys` to `false` to only permit auto-generated keys for a collection.
 
 ## Synchronous replication of collections
 

site/content/3.11/develop/http-api/administration.md

@@ -46,6 +46,7 @@ paths:
             the `details` object may vary depending on platform and ArangoDB version.
           schema:
             type: boolean
+            default: false
       responses:
         '200':
           description: |
@@ -601,6 +602,11 @@ paths:
       description: |
         Return availability information about a server.
 
+        The response is a JSON object with an attribute "mode". The "mode" can either
+        be "readonly", if the server is in read-only mode, or "default", if it is not.
+        Please note that the JSON object with "mode" is only returned in case the server
+        does not respond with HTTP response code 503.
+
         This is a public API so it does *not* require authentication. It is meant to be
         used only in the context of server monitoring.
       responses:
@@ -1146,6 +1152,7 @@ paths:
              - Ongoing low priority requests
           schema:
             type: boolean
+            default: false
       responses:
         '200':
           description: |
@@ -1280,13 +1287,13 @@ paths:
                 changeLevel:
                   description: |
                     whether or not compacted data should be moved to the minimum possible level.
-                    The default value is `false`.
                   type: boolean
+                  default: false
                 compactBottomMostLevel:
                   description: |
                     Whether or not to compact the bottommost level of data.
-                    The default value is `false`.
                   type: boolean
+                  default: false
       responses:
         '200':
           description: |
@@ -1353,16 +1360,10 @@ paths:
         The call returns an object with the servers request information
       requestBody:
         content:
-          application/json:
+          application/octet-stream:
             schema:
-              type: object
-              required:
-                - body
-              properties:
-                body:
-                  description: |
-                    The request body can be of any type and is simply forwarded.
-                  type: string
+              description: |
+                The request body can be of any type and is simply forwarded.
       parameters:
         - name: database-name
           in: path
@@ -1545,8 +1546,9 @@ paths:
         directly, otherwise a string produced by JSON.stringify will be
         returned.
 
-        Note that this API endpoint will only be present if the server was
-        started with the option `--javascript.allow-admin-execute true`.
+        Note that this API endpoint is available if the server has been
+        started with the `--javascript.allow-admin-execute` startup options
+        enabled.
 
         The default value of this option is `false`, which disables the execution of
         user-defined code and disables this API endpoint entirely.
@@ -1562,16 +1564,10 @@ paths:
             type: string
       requestBody:
         content:
-          application/json:
+          text/javascript:
             schema:
-              type: object
-              required:
-                - body
-              properties:
-                body:
-                  description: |
-                    The request body is the JavaScript code to be executed.
-                  type: string
+              description: |
+                The request body is the JavaScript code to be executed.
       responses:
         '200':
           description: |

site/content/3.11/develop/http-api/analyzers.md

@@ -54,8 +54,8 @@ paths:
                 features:
                   description: |
                     The set of features to set on the Analyzer generated fields.
-                    The default value is an empty array.
                   type: array
+                  default: []
                   uniqueItems: true
                   items:
                     type: string
@@ -249,9 +249,9 @@ paths:
           required: false
           description: |
             The Analyzer configuration should be removed even if it is in-use.
-            The default value is `false`.
           schema:
             type: boolean
+            default: false
       responses:
         '200':
           description: |

site/content/3.11/develop/http-api/batch-requests.md

@@ -278,17 +278,11 @@ paths:
             type: string
       requestBody:
         content:
-          application/json:
+          'text/plain; charset=utf-8':
             schema:
-              type: object
-              required:
-                - body
-              properties:
-                body:
-                  description: |
-                    The multipart batch request, consisting of the envelope and the individual
-                    batch parts.
-                  type: string
+              description: |
+                The multipart batch request, consisting of the envelope and the individual
+                batch parts.
       responses:
         '200':
           description: |

site/content/3.11/develop/http-api/cluster.md

@@ -380,6 +380,7 @@ paths:
                     You can send another request when the DB-Server is already in maintenance mode
                     to extend the timeout.
                   type: integer
+                  default: 3600
       responses:
         '200':
           description: |
@@ -808,37 +809,44 @@ paths:
                   type: number
                 maximumNumberOfMoves:
                   description: |
-                    Maximum number of moves to be computed. (Default: `1000`)
-                  type: number
+                    Maximum number of moves to be computed.
+                  type: integer
+                  default: 1000
                 leaderChanges:
                   description: |
-                    Allow leader changes without moving data. (Default: `true`)
+                    Allow leader changes without moving data.
                   type: boolean
+                  default: true
                 moveLeaders:
                   description: |
-                    Allow moving leaders. (Default: `false`)
+                    Allow moving leaders.
                   type: boolean
+                  default: false
                 moveFollowers:
                   description: |
-                    Allow moving followers. (Default: `false`)
+                    Allow moving followers.
                   type: boolean
+                  default: false
                 excludeSystemCollections:
                   description: |
-                    Ignore system collections in the rebalance plan. (Default: `false`)
+                    Ignore system collections in the rebalance plan.
                   type: boolean
+                  default: false
                 piFactor:
                   description: |
-                    A weighting factor that should remain untouched. (Default: `256e6`)
+                    A weighting factor that should remain untouched.
 
                     If a collection has more shards than there are DB-Servers, there can be a subtle
                     form of leader imbalance. Some DB-Servers may be responsible for more shards as
                     leader than others. The `piFactor` adjusts how much weight such imbalances get
                     in the overall imbalance score.
-                  type: number
+                  type: integer
+                  default: 256e6
                 databasesExcluded:
                   description: |
-                    A list of database names to exclude from the analysis. (Default: `[]`)
+                    A list of database names to exclude from the analysis.
                   type: array
+                  default: []
                   items:
                     type: string
       responses:
@@ -1218,37 +1226,44 @@ paths:
                   type: number
                 maximumNumberOfMoves:
                   description: |
-                    Maximum number of moves to be computed. (Default: `1000`)
-                  type: number
+                    Maximum number of moves to be computed.
+                  type: integer
+                  default: 1000
                 leaderChanges:
                   description: |
-                    Allow leader changes without moving data. (Default: `true`)
+                    Allow leader changes without moving data.
                   type: boolean
+                  default: true
                 moveLeaders:
                   description: |
-                    Allow moving leaders. (Default: `false`)
+                    Allow moving leaders.
                   type: boolean
+                  default: false
                 moveFollowers:
                   description: |
-                    Allow moving followers. (Default: `false`)
+                    Allow moving followers.
                   type: boolean
+                  default: false
                 excludeSystemCollections:
                   description: |
-                    Ignore system collections in the rebalance plan. (Default: `false`)
+                    Ignore system collections in the rebalance plan.
                   type: boolean
+                  default: false
                 piFactor:
                   description: |
-                    A weighting factor that should remain untouched. (Default: `256e6`)
+                    A weighting factor that should remain untouched.
 
                     If a collection has more shards than there are DB-Servers, there can be a subtle
                     form of leader imbalance. Some DB-Servers may be responsible for more shards as
                     leader than others. The `piFactor` adjusts how much weight such imbalances get
                     in the overall imbalance score.
-                  type: number
+                  type: integer
+                  default: 256e6
                 databasesExcluded:
                   description: |
-                    A list of database names to exclude from the analysis. (Default: `[]`)
+                    A list of database names to exclude from the analysis.
                   type: array
+                  default: []
                   items:
                     type: string
       responses: