Added basic schema documentation to Thing Descriptions

Author: jtc42

labthings/server/decorators.py

@@ -100,6 +100,32 @@ def ThingProperty(viewcls):
 thing_property = ThingProperty
 
 
+class PropertySchema(object):
+    def __init__(self, schema, code=200):
+        """
+        :param schema: a dict of whose keys will make up the final
+                        serialized response output
+        """
+        self.schema = schema
+        self.code = code
+
+    def __call__(self, viewcls):
+        update_spec(viewcls, {"_propertySchema": self.schema})
+
+        if hasattr(viewcls, "get") and callable(viewcls.get):
+            viewcls.get = marshal_with(self.schema, code=self.code)(viewcls.get)
+
+        if hasattr(viewcls, "post") and callable(viewcls.post):
+            viewcls.post = marshal_with(self.schema, code=self.code)(viewcls.post)
+            viewcls.post = use_args(self.schema)(viewcls.post)
+
+        if hasattr(viewcls, "put") and callable(viewcls.put):
+            viewcls.put = marshal_with(self.schema, code=self.code)(viewcls.put)
+            viewcls.put = use_args(self.schema)(viewcls.put)
+
+        return viewcls
+
+
 class use_body(object):
     """
     Gets the request body as a single value and adds it as a positional argument
@@ -149,7 +175,11 @@ class use_args(object):
 
     def __init__(self, schema, **kwargs):
         self.schema = schema
-        self.wrapper = flaskparser.use_args(schema, **kwargs)
+
+        if isinstance(schema, Field):
+            self.wrapper = use_body(schema, **kwargs)
+        else:
+            self.wrapper = flaskparser.use_args(schema, **kwargs)
 
     def __call__(self, f):
         # Pass params to call function attribute for external access

labthings/server/spec/__init__.py

@@ -130,6 +130,13 @@ def method2operation(method: callable, spec: APISpec):
 
 
 def convert_schema(schema, spec: APISpec):
+    """
+    Ensure that a given schema is either a real Marshmallow schema, 
+    or is a dictionary describing the schema inline.
+
+    Marshmallow schemas are left as they are so that the APISpec module
+    can add them to the "schemas" list in our APISpec documentation.
+    """
     if isinstance(schema, BaseSchema):
         return schema
     elif isinstance(schema, Mapping):
@@ -143,6 +150,9 @@ def convert_schema(schema, spec: APISpec):
 
 
 def map2properties(schema, spec: APISpec):
+    """
+    Convert any dictionary-like map of Marshmallow fields into a dictionary describing it's JSON schema
+    """
     marshmallow_plugin = next(
         plugin for plugin in spec.plugins if isinstance(plugin, MarshmallowPlugin)
     )
@@ -157,13 +167,36 @@ def map2properties(schema, spec: APISpec):
         else:
             d[k] = v
 
-    return {"properties": d}
+    return {"type": "object", "properties": d}
 
 
 def field2property(field, spec: APISpec):
+    """
+    Convert a single Marshmallow field into a JSON schema of that field
+    """
     marshmallow_plugin = next(
         plugin for plugin in spec.plugins if isinstance(plugin, MarshmallowPlugin)
     )
     converter = marshmallow_plugin.converter
 
     return converter.field2property(field)
+
+
+def schema2json(schema, spec: APISpec):
+    """
+    Convert any Marshmallow schema, field, or dictionary of fields stright to a JSON schema
+    This should not be used when generating APISpec documentation, otherwise schemas wont
+    be listed in the "schemas" list. This is used, for example, in the Thing Description.
+    """
+    if not isinstance(schema, BaseSchema):
+        schema = convert_schema(schema, spec)
+
+    if isinstance(schema, BaseSchema):
+        marshmallow_plugin = next(
+            plugin for plugin in spec.plugins if isinstance(plugin, MarshmallowPlugin)
+        )
+        converter = marshmallow_plugin.converter
+
+        schema = converter.schema2jsonschema(schema)
+
+    return schema

labthings/server/views/docs/__init__.py

@@ -12,7 +12,7 @@
 
 from ...view import View
 from ...find import current_labthing
-from ...spec import rule_to_path, rule_to_params
+from ...spec import get_spec, rule_to_path, rule_to_params, convert_schema, schema2json
 
 
 class APISpecView(View):
@@ -46,14 +46,40 @@ def get(self):
 
         props = {}
         for key, prop in current_labthing().properties.items():
+            props[key] = {}
             prop_rules = current_app.url_map._rules_by_endpoint.get(prop.endpoint)
             prop_urls = [rule_to_path(rule) for rule in prop_rules]
 
-            props[key] = {}
+            # Look for a _propertySchema in the Property classes API SPec
+            prop_spec = get_spec(prop)
+            prop_schema = prop_spec.get("_propertySchema")
+            if not prop_schema:
+                # If prop is read-only
+                if hasattr(prop, "get") and not (
+                    hasattr(prop, "post") or hasattr(prop, "put")
+                ):
+                    prop_schema = get_spec(prop.get).get("_schema").get(200)
+                # If prop is write-only
+                elif not hasattr(prop, "get") and (
+                    hasattr(prop, "post") or hasattr(prop, "put")
+                ):
+                    if hasattr(prop, "post"):
+                        prop_schema = get_spec(prop.post).get("_params")
+                    elif hasattr(prop, "put"):
+                        prop_schema = get_spec(prop.put).get("_params")
+                    else:
+                        prop_schema = {}
+
+            prop_json_schema = schema2json(prop_schema, current_labthing().spec)
+
+            props[key].update(prop_json_schema)
+
+            # Generate the rest of the description
             props[key]["title"] = prop.__name__
-            # TODO: Get description from __apispec__ preferentially
-            props[key]["description"] = get_docstring(prop) or (
-                get_docstring(prop.get) if hasattr(prop, "get") else ""
+            props[key]["description"] = (
+                props[key].get("description")
+                or get_docstring(prop)
+                or (get_docstring(prop.get) if hasattr(prop, "get") else "")
             )
             props[key]["readOnly"] = not (
                 hasattr(prop, "post") or hasattr(prop, "put") or hasattr(prop, "delete")