Bug fix/fix swagger datatype (#9045) (#9602)

* Bug fix/fix swagger datatype (#9045)

* remove http so https arangos will work

* verify that query parameters are proper swagger data types, fix offending documentation files

* return the actual type - not the list of available ones

* check formats

* there is no uint64 in swagger

* Fresh Swagger

Documentation/DocuBlocks/Rest/Replication/get_api_wal_access_tail.md

@@ -20,7 +20,7 @@ Should be set to the value of the *x-arango-replication-lastscanned* header
 or alternatively 0 on first try. This allows the rocksdb engine to break up
 large transactions over multiple responses. 
 
-@RESTQUERYPARAM{global,bool,optional}
+@RESTQUERYPARAM{global,boolean,optional}
 Whether operations for all databases should be included. When set to *false*
 only the operations for the current database are included. The value *true* is
 only valid on the *_system* database. The default is *false*.

Documentation/DocuBlocks/Rest/Views/patch_api_view_properties_iresearch.md

@@ -12,7 +12,7 @@ The name of the view.
 The view properties. If specified, then *properties* should be a JSON object
 containing the following attributes:
 
-@RESTSTRUCT{cleanupIntervalStep,post_api_view_props,integer,optional,uint64}
+@RESTSTRUCT{cleanupIntervalStep,post_api_view_props,integer,optional,int64}
 Wait at least this many commits between removing unused files in the
 ArangoSearch data directory (default: 10, to disable use: 0).
 For the case where the consolidation policies merge segments often (i.e. a lot
@@ -29,7 +29,7 @@ _Background:_
   However, the files for the released states/snapshots are left on disk, and
   only removed by "cleanup" operation.
 
-@RESTSTRUCT{commitIntervalMsec,post_api_view_props,integer,optional,uint64}
+@RESTSTRUCT{commitIntervalMsec,post_api_view_props,integer,optional,int64}
 Wait at least this many milliseconds between committing view data store
 changes and making documents visible to queries (default: 1000, to disable
 use: 0).
@@ -52,7 +52,7 @@ _Background:_
   still continue to return a repeatable-read state.
 
 
-@RESTSTRUCT{consolidationIntervalMsec,post_api_view_props,integer,optional,uint64}
+@RESTSTRUCT{consolidationIntervalMsec,post_api_view_props,integer,optional,int64}
 Wait at least this many milliseconds between applying 'consolidationPolicy' to
 consolidate view data store and possibly release space on the filesystem
 (default: 60000, to disable use: 0).

Documentation/DocuBlocks/Rest/Views/post_api_view_iresearch.md

@@ -13,7 +13,7 @@ The type of the view. must be equal to *"arangosearch"*
 The view properties. If specified, then *properties* should be a JSON object
 containing the following attributes:
 
-@RESTSTRUCT{cleanupIntervalStep,post_api_view_props,integer,optional,uint64}
+@RESTSTRUCT{cleanupIntervalStep,post_api_view_props,integer,optional,int64}
 Wait at least this many commits between removing unused files in the
 ArangoSearch data directory (default: 10, to disable use: 0).
 For the case where the consolidation policies merge segments often (i.e. a lot
@@ -30,7 +30,7 @@ _Background:_
   However, the files for the released states/snapshots are left on disk, and
   only removed by "cleanup" operation.
 
-@RESTSTRUCT{commitIntervalMsec,post_api_view_props,integer,optional,uint64}
+@RESTSTRUCT{commitIntervalMsec,post_api_view_props,integer,optional,int64}
 Wait at least this many milliseconds between committing view data store
 changes and making documents visible to queries (default: 1000, to disable
 use: 0).
@@ -53,7 +53,7 @@ _Background:_
   still continue to return a repeatable-read state.
 
 
-@RESTSTRUCT{consolidationIntervalMsec,post_api_view_props,integer,optional,uint64}
+@RESTSTRUCT{consolidationIntervalMsec,post_api_view_props,integer,optional,int64}
 Wait at least this many milliseconds between applying 'consolidationPolicy' to
 consolidate view data store and possibly release space on the filesystem
 (default: 60000, to disable use: 0).

Documentation/DocuBlocks/Rest/Views/put_api_view_properties_iresearch.md

@@ -12,7 +12,7 @@ The name of the view.
 The view properties. If specified, then *properties* should be a JSON object
 containing the following attributes:
 
-@RESTSTRUCT{cleanupIntervalStep,post_api_view_props,integer,optional,uint64}
+@RESTSTRUCT{cleanupIntervalStep,post_api_view_props,integer,optional,int64}
 Wait at least this many commits between removing unused files in the
 ArangoSearch data directory (default: 10, to disable use: 0).
 For the case where the consolidation policies merge segments often (i.e. a lot
@@ -29,7 +29,7 @@ _Background:_
   However, the files for the released states/snapshots are left on disk, and
   only removed by "cleanup" operation.
 
-@RESTSTRUCT{commitIntervalMsec,post_api_view_props,integer,optional,uint64}
+@RESTSTRUCT{commitIntervalMsec,post_api_view_props,integer,optional,int64}
 Wait at least this many milliseconds between committing view data store
 changes and making documents visible to queries (default: 1000, to disable
 use: 0).
@@ -52,7 +52,7 @@ _Background:_
   still continue to return a repeatable-read state.
 
 
-@RESTSTRUCT{consolidationIntervalMsec,post_api_view_props,integer,optional,uint64}
+@RESTSTRUCT{consolidationIntervalMsec,post_api_view_props,integer,optional,int64}
 Wait at least this many milliseconds between applying 'consolidationPolicy' to
 consolidate view data store and possibly release space on the filesystem
 (default: 60000, to disable use: 0).

utils/generateSwagger.py

@@ -65,7 +65,34 @@ swagger = {
         }
     },
     "basePath": "/",
-    "definitions": {},
+    "definitions": {
+        "ARANGO_ERROR": {
+            "description": "An ArangoDB Error code",
+            "type": "integer"
+        },
+        "ArangoError": {
+            "description": "the arangodb error type",
+            "properties": {
+                "code": {
+                    "description": "the HTTP Status code",
+                    "type": "integer"
+                },
+                "error": {
+                    "description": "boolean flag to indicate whether an error occurred (*true* in this case)",
+                    "type": "boolean"
+                },
+                "errorMessage": {
+                    "description": "a descriptive error message describing what happened, may contain additional information",
+                    "type": "string"
+                },
+                "errorNum": {
+                    "description": "the ARANGO_ERROR code",
+                    "type": "integer"
+                }
+            }
+        }
+        
+    },
     "paths" : {}
 }
 
@@ -76,6 +103,7 @@ swagger = {
 swaggerBaseTypes = [
     'object',
     'array',
+    'number',
     'integer',
     'long',
     'float',
@@ -89,6 +117,11 @@ swaggerBaseTypes = [
     'password'
 ]
 
+swaggerFormats = {
+    "number": ["", "float", "double"],
+    "integer": ["", "int32", "int64"]
+}
+
 ################################################################################
 ### @brief length of the swagger definition namespace
 ################################################################################
@@ -362,10 +395,10 @@ class StateMachine:
                     raise RuntimeError("Invalid target %s" % newState)
                 else:
                     handler = newState
-        except:
+        except Exception as x:
             print >> sys.stderr, "while parsing '" + self.fn + "'"
             print >> sys.stderr, "trying to use handler '"  + handler.__name__ + "'"
-            raise
+            raise x
 
 ################################################################################
 ### @brief Regexen
@@ -506,9 +539,9 @@ def generic_handler_desc(cargo, r, message, op, para, name):
             if op:
                 try:
                     operation[op].append(para)
-                except AttributeError:
+                except AttributeError as x:
                     print >> sys.stderr, "trying to set '%s' on operations - failed. '%s'" % (op, para)
-                    raise
+                    raise x
             return next, c
 
         line = Typography(line)
@@ -525,7 +558,7 @@ def start_docublock(cargo, r=Regexen()):
             currentDocuBlock = last.split(' ')[1].rstrip()
     except Exception as x:
         print >> sys.stderr, "failed to fetch docublock in '" + last + "': " + str(x)
-        raise
+        raise x
 
     return generic_handler(cargo, r, 'start_docublock')
 
@@ -715,7 +748,7 @@ def restbodyparam(cargo, r=Regexen()):
     except Exception:
         print >> sys.stderr, "RESTBODYPARAM: 4 arguments required. You gave me: " + parameters(last)
         print >> sys.stderr, "In this docublock: " + currentDocuBlock
-        raise
+        raise Exception("Argument count error")
 
     CheckReqOpt(required)
     if required == 'required':
@@ -784,6 +817,9 @@ def restbodyparam(cargo, r=Regexen()):
     elif ptype == 'object':
         swagger['definitions'][currentDocuBlock]['properties'][name]['additionalProperties'] = {}
     elif ptype != 'string':
+        if ptype in swaggerFormats and ptype2 not in swaggerFormats[ptype]:
+            print >> sys.stderr, "RESTSTRUCT: ptype2 (format)[" + ptype2 + "]  not valid: " + parameters(last)
+            raise Exception("'%s' is not one of %s!" % (ptype2, str(swaggerFormats)))
         swagger['definitions'][currentDocuBlock]['properties'][name]['format'] = ptype2
 
 
@@ -844,7 +880,7 @@ def reststruct(cargo, r=Regexen()):
         (name, className, ptype, required, ptype2) = parameters(last).split(',')
     except Exception:
         print >> sys.stderr, "RESTSTRUCT: 5 arguments required (name, className, ptype, required, ptype2). You gave me: " + parameters(last)
-        raise
+        raise Exception("Argument count error")
 
     CheckReqOpt(required)
     if required == 'required':
@@ -894,6 +930,9 @@ def reststruct(cargo, r=Regexen()):
                                     'description')
 
     elif ptype != 'string' and ptype != 'boolean':
+        if ptype in swaggerFormats and ptype2 not in swaggerFormats[ptype]:
+            print >> sys.stderr, "RESTSTRUCT: ptype2 (format)[" + ptype2 + "]  not valid: " + parameters(last)
+            raise Exception("'%s' is not one of %s!" % (ptype2, str(swaggerFormats)))
         swagger['definitions'][className]['properties'][name]['format'] = ptype2
 
     return generic_handler_desc(cargo, r, "restbodyparam", None,
@@ -905,7 +944,7 @@ def reststruct(cargo, r=Regexen()):
 ################################################################################
 
 def restqueryparam(cargo, r=Regexen()):
-    global swagger, operation, httpPath, method
+    global swagger, operation, httpPath, method, swaggerBaseTypes
     (dummy, last) = cargo
 
     parametersList = parameters(last).split(',')
@@ -915,12 +954,17 @@ def restqueryparam(cargo, r=Regexen()):
         required = True
     else:
         required = False
+    swaggerType = parametersList[1].lower()
+    
+    if swaggerType not in swaggerBaseTypes:
+        print >> sys.stderr, "RESTQUERYPARAM is supposed to be a swagger type."
+        raise Exception("'%s' is not one of %s!" % (swaggerType, str(swaggerBaseTypes)))
 
     para = {
         'name': parametersList[0],
         'in': 'query',
         'description': '',
-        'type': parametersList[1].lower(),
+        'type': swaggerType,
         'required': required
         }
 
@@ -1152,7 +1196,7 @@ def example_arangosh_run(cargo, r=Regexen()):
         examplefile = open(fn)
     except:
         print >> sys.stderr, "Failed to open example file:\n  '%s'" % fn
-        raise
+        raise Exception("failed to open example file:" + fn)
     operation['x-examples'][currentExample] = '\n\n**Example:**\n ' + exampleHeader.strip('\n ') + '\n\n<pre>'
 
     for line in examplefile.readlines():
@@ -1275,7 +1319,7 @@ def getReference(name, source, verb):
     except Exception:
         print >>sys.stderr, "No reference in: "
         print >>sys.stderr, name
-        raise
+        raise Exception("No reference in: " + name)
     if not ref in swagger['definitions']:
         fn = ''
         if verb:
@@ -1419,7 +1463,7 @@ for name, filenames in sorted(files.items(), key=operator.itemgetter(0)):
             getOneApi(infile, name + " - " + ', '.join(filenames), fn)
         except Exception as x:
             print >> sys.stderr, "\nwhile parsing file: '%s' error: %s" % (thisfn, x)
-            raise
+            raise Exception("while parsing file '%s' error: %s" %(thisfn, x))
         infile.close()
         currentDocuBlock = None
         lastDocuBlock = None