Update events to use Swagger 1.3 subtyping, and related aftermath

This patch started with the simple idea of changing the /events data
model to be more sane. The original model would send out events like:

    { "stasis_start": { "args": [], "channel": { ... } } }

The event discriminator was the field name instead of being a value in
the object, due to limitations in how Swagger 1.1 could model objects.
While technically sufficient in communicating event information, it was
really difficult to deal with in terms of client side JSON handling.

This patch takes advantage of a proposed extension[1] to Swagger which
allows type variance through the use of a discriminator field. This had
a domino effect that made this a surprisingly large patch.

 [1]: https://groups.google.com/d/msg/wordnik-api/EC3rGajE0os/ey_5dBI_jWcJ

In changing the models, I also had to change the swagger_model.py
processor so it can handle the type discriminator and subtyping. I took
that a big step forward, and using that information to generate an
ari_model module, which can validate a JSON object against the Swagger
model.

The REST and WebSocket generators were changed to take advantage of the
validators. If compiled with AST_DEVMODE enabled, JSON objects that
don't match their corresponding models will not be sent out. For REST
API calls, a 500 Internal Server response is sent. For WebSockets, the
invalid JSON message is replaced with an error message.

Since this took over about half of the job of the existing JSON
generators, and the .to_json virtual function on messages took over the
other half, I reluctantly removed the generators.

The validators turned up all sorts of errors and inconsistencies in our
data models, and the code. These were cleaned up, with checks in the
code generator avoid some of the consistency problems in the future.

 * The model for a channel snapshot was trimmed down to match the
   information sent via AMI. Many of the field being sent were not
   useful in the general case.
 * The model for a bridge snapshot was updated to be more consistent
   with the other ARI models.

Another impact of introducing subtyping was that the swagger-codegen
documentation generator was insufficient (at least until it catches up
with Swagger 1.2). I wanted it to be easier to generate docs for the API
anyways, so I ported the wiki pages to use the Asterisk Swagger
generator. In the process, I was able to clean up many of the model
links, which would occasionally give inconsistent results on the wiki. I
also added error responses to the wiki docs, making the wiki
documentation more complete.

Finally, since Stasis-HTTP will now be named Asterisk REST Interface
(ARI), any new functions and files I created carry the ari_ prefix. I
changed a few stasis_http references to ari where it was non-intrusive
and made sense.

(closes issue ASTERISK-21885)
Review: https://reviewboard.asterisk.org/r/2639/



git-svn-id: https://origsvn.digium.com/svn/asterisk/trunk@393529 65c4cc65-6c06-0410-ace0-fbb531ad65f3

1 files changed, 38 insertions, 49 deletions

diff --git a/rest-api-templates/asterisk_processor.py b/rest-api-templates/asterisk_processor.py
index af5f5bdfe..0260b6b55 100644
--- a/rest-api-templates/asterisk_processor.py
+++ b/rest-api-templates/asterisk_processor.py
@@ -24,6 +24,11 @@ import re
 
 from swagger_model import *
 
+try:
+    from collections import OrderedDict
+except ImportError:
+    from odict import OrderedDict
+
 
 def simple_name(name):
     """Removes the {markers} from a path segement.
@@ -35,6 +40,14 @@ def simple_name(name):
     return name
 
 
+def wikify(str):
+    """Escapes a string for the wiki.
+
+    @param str: String to escape
+    """
+    return re.sub(r'([{}\[\]])', r'\\\1', str)
+
+
 def snakify(name):
     """Helper to take a camelCase or dash-seperated name and make it
     snake_case.
@@ -107,6 +120,7 @@ class PathSegment(Stringify):
         """
         return len(self.__children)
 
+
 class AsteriskProcessor(SwaggerPostProcessor):
     """A SwaggerPostProcessor which adds fields needed to generate Asterisk
     RESTful HTTP binding code.
@@ -131,12 +145,17 @@ class AsteriskProcessor(SwaggerPostProcessor):
         'double': 'atof',
     }
 
-    def process_api(self, resource_api, context):
+    def __init__(self, wiki_prefix):
+        self.wiki_prefix = wiki_prefix
+
+    def process_resource_api(self, resource_api, context):
+        resource_api.wiki_prefix = self.wiki_prefix
         # Derive a resource name from the API declaration's filename
         resource_api.name = re.sub('\..*', '',
                                    os.path.basename(resource_api.path))
-        # Now in all caps, from include guard
+        # Now in all caps, for include guard
         resource_api.name_caps = resource_api.name.upper()
+        resource_api.name_title = resource_api.name.capitalize()
         # Construct the PathSegement tree for the API.
         if resource_api.api_declaration:
             resource_api.root_path = PathSegment('', None)
@@ -145,17 +164,6 @@ class AsteriskProcessor(SwaggerPostProcessor):
                 for operation in api.operations:
                     segment.operations.append(operation)
                 api.full_name = segment.full_name
-            resource_api.api_declaration.has_events = False
-            for model in resource_api.api_declaration.models:
-                if model.id == "Event":
-                    resource_api.api_declaration.has_events = True
-                    break
-            if resource_api.api_declaration.has_events:
-                resource_api.api_declaration.events = \
-                    [self.process_model(model, context) for model in \
-                        resource_api.api_declaration.models if model.id != "Event"]
-            else:
-                resource_api.api_declaration.events = []
 
             # Since every API path should start with /[resource], root should
             # have exactly one child.
@@ -169,6 +177,9 @@ class AsteriskProcessor(SwaggerPostProcessor):
                     "API declaration name should match", context)
             resource_api.root_full_name = resource_api.root_path.full_name
 
+    def process_api(self, api, context):
+        api.wiki_path = wikify(api.path)
+
     def process_operation(self, operation, context):
         # Nicknames are camelcase, Asterisk coding is snake case
         operation.c_nickname = snakify(operation.nickname)
@@ -179,7 +190,7 @@ class AsteriskProcessor(SwaggerPostProcessor):
     def process_parameter(self, parameter, context):
         if not parameter.data_type in self.type_mapping:
             raise SwaggerError(
-                "Invalid parameter type %s" % paramter.data_type, context)
+                "Invalid parameter type %s" % parameter.data_type, context)
         # Parameter names are camelcase, Asterisk convention is snake case
         parameter.c_name = snakify(parameter.name)
         parameter.c_data_type = self.type_mapping[parameter.data_type]
@@ -191,41 +202,19 @@ class AsteriskProcessor(SwaggerPostProcessor):
             parameter.c_space = ' '
 
     def process_model(self, model, context):
+        model.description_dox = model.description.replace('\n', '\n * ')
+        model.description_dox = re.sub(' *\n', '\n', model.description_dox)
         model.c_id = snakify(model.id)
-        model.channel = False
-        model.channel_desc = ""
-        model.bridge = False
-        model.bridge_desc = ""
-        model.properties = [self.process_property(model, prop, context) for prop in model.properties]
-        model.properties = [prop for prop in model.properties if prop]
-	model.has_properties = (len(model.properties) != 0)
         return model
 
-    def process_property(self, model, prop, context):
-        # process channel separately since it will be pulled out
-        if prop.name == 'channel' and prop.type == 'Channel':
-            model.channel = True
-            model.channel_desc = prop.description or ""
-            return None
-
-        # process bridge separately since it will be pulled out
-        if prop.name == 'bridge' and prop.type == 'Bridge':
-            model.bridge = True
-            model.bridge_desc = prop.description or ""
-            return None
-
-	prop.c_name = snakify(prop.name)
-        if prop.type in self.type_mapping:
-            prop.c_type = self.type_mapping[prop.type]
-            prop.c_convert = self.convert_mapping[prop.c_type]
-        else:
-            prop.c_type = "Property type %s not mappable to a C type" % (prop.type)
-            prop.c_convert = "Property type %s not mappable to a C conversion" % (prop.type)
-            #raise SwaggerError(
-            #    "Invalid property type %s" % prop.type, context)
-        # You shouldn't put a space between 'char *' and the variable
-        if prop.c_type.endswith('*'):
-            prop.c_space = ''
-        else:
-            prop.c_space = ' '
-        return prop
+    def process_property(self, prop, context):
+        if "-" in prop.name:
+            raise SwaggerError("Property names cannot have dashes", context)
+        if prop.name != prop.name.lower():
+            raise SwaggerError("Property name should be all lowercase",
+                               context)
+
+    def process_type(self, swagger_type, context):
+        swagger_type.c_name = snakify(swagger_type.name)
+        swagger_type.c_singular_name = snakify(swagger_type.singular_name)
+        swagger_type.wiki_name = wikify(swagger_type.name)