parameter description support

.gitignore

@@ -71,3 +71,4 @@ pip-selfcheck.json
 
 # allowing transmute-core's lib directory
 !transmute_core/swagger/static/lib
+.pytest_cache

transmute_core/attributes/__init__.py

@@ -8,7 +8,7 @@ def __init__(self, paths=None, methods=None, tags=None,
                  query_parameters=None, body_parameters=None,
                  header_parameters=None, path_parameters=None,
                  error_exceptions=None, response_types=None,
-                 success_code=200):
+                 success_code=200, parameter_descriptions=None):
         self.paths = set(paths or [])
         self.methods = set(methods or ["GET"])
         self.tags = set(tags or [])
@@ -18,6 +18,7 @@ def __init__(self, paths=None, methods=None, tags=None,
         self.header_parameters = set(header_parameters or [])
         self.path_parameters = set(path_parameters or [])
         self.error_exceptions = set(error_exceptions or [])
+        self.parameter_descriptions = parameter_descriptions or {}
         self.response_types = {}
         for code, response in (response_types or {}).items():
             if not isinstance(response, ResponseType):
@@ -48,6 +49,9 @@ def __or__(self, other):
         for k, v in other.response_types.items():
             response_types[k] = v
 
+        parameter_descriptions = self.parameter_descriptions.copy()
+        parameter_descriptions.update(other.parameter_descriptions)
+
         return TransmuteAttributes(
             paths=(self.paths | other.paths),
             methods=(self.methods | other.methods),
@@ -58,6 +62,7 @@ def __or__(self, other):
             header_parameters=(self.header_parameters | other.header_parameters),
             path_parameters=(self.path_parameters | other.path_parameters),
             error_exceptions=(self.error_exceptions | other.error_exceptions),
+            parameter_descriptions=parameter_descriptions,
             response_types=response_types
         )
 
@@ -67,7 +72,7 @@ def __str__(self):
                   "query_parameters", "body_parameters",
                   "header_parameters", "path_parameters",
                   "error_exceptions", "response_types",
-                  "success_code"]:
+                  "success_code", "parameter_descriptions"]:
             arg_list.append("{0}={1}".format(
                 k, getattr(self, k)
             ))

transmute_core/attributes/response_type.py

@@ -22,6 +22,7 @@ class ResponseType(object):
         ],
         default=attr.Factory(dict)
     )
+    type_description = attr.ib(default="")
 
     def swagger_definition(self, context):
         if self.type is not None:
@@ -37,6 +38,8 @@ def swagger_definition(self, context):
                 header_definition["description"] = header["description"]
             headers[name] = header_definition
 
+        if self.type_description:
+            schema["description"] = self.type_description
         response = {
             "description": self.description,
             "schema": schema

transmute_core/decorators.py

@@ -26,6 +26,9 @@ def describe(**kwargs):
 
     :param list(str) path_parameters: the arguments that are specified by the path. By default, arguments
             that are found in the path are used first before the query_parameters and body_parameters.
+
+    :param list(str) parameter_descriptions: descriptions for each parameter, keyed by attribute name.
+            this will appear in the swagger documentation.
     """
     # if we have a single method, make it a list.
     if isinstance(kwargs.get("paths"), string_type):

transmute_core/function/parameters.py

@@ -31,21 +31,30 @@ def get_parameters(signature, transmute_attrs, arguments_to_ignore=None):
     for key in ["query", "header", "path"]:
         param_set = getattr(params, key)
         explicit_parameters = getattr(transmute_attrs, key + "_parameters")
-        used_keys |= load_parameters(param_set, explicit_parameters, signature)
+        used_keys |= load_parameters(
+            param_set, explicit_parameters, signature, transmute_attrs
+        )
 
     body_parameters = transmute_attrs.body_parameters
     if isinstance(body_parameters, str):
         name = body_parameters
-        params.body = Param(argument_name=name,
-                            arginfo=signature.get_argument(name))
+        params.body = Param(
+            argument_name=name,
+            description=transmute_attrs.parameter_descriptions.get(name),
+            arginfo=signature.get_argument(name)
+        )
         used_keys.add(name)
     else:
         used_keys |= load_parameters(params.body, transmute_attrs.body_parameters,
-                                     signature)
+                                     signature, transmute_attrs)
 
     # extract the parameters from the paths
     for name in _extract_path_parameters_from_paths(transmute_attrs.paths):
-        params.path[name] = Param(argument_name=name, arginfo=signature.get_argument(name))
+        params.path[name] = Param(
+            argument_name=name,
+            description=transmute_attrs.parameter_descriptions.get(name),
+            arginfo=signature.get_argument(name)
+        )
         used_keys.add(name)
 
     # check the method type, and decide if the parameters should be extracted
@@ -60,7 +69,11 @@ def get_parameters(signature, transmute_attrs, arguments_to_ignore=None):
         if arginfo.name in used_keys:
             continue
         used_keys.add(arginfo.name)
-        default_params[arginfo.name] = Param(arginfo.name, arginfo=arginfo)
+        default_params[arginfo.name] = Param(
+            arginfo.name,
+            description=transmute_attrs.parameter_descriptions.get(arginfo.name),
+            arginfo=arginfo
+        )
 
     return params
 
@@ -86,10 +99,13 @@ def _extract_path_parameters_from_paths(paths):
     return params
 
 
-def load_parameters(param_set, param_list, signature):
+def load_parameters(param_set, param_list, signature, transmute_attrs):
     used_keys = set()
     for name in param_list:
-        param_set[name] = Param(argument_name=name,
-                                arginfo=signature.get_argument(name))
+        param_set[name] = Param(
+            argument_name=name,
+            description=transmute_attrs.parameter_descriptions.get(name),
+            arginfo=signature.get_argument(name)
+        )
         used_keys.add(name)
     return used_keys

transmute_core/function/transmute_function.py

@@ -153,10 +153,12 @@ def _parse_response_types(argspec, attrs):
         from the given parameters, return back the response type dictionaries.
         """
         return_type = argspec.annotations.get("return") or None
+        type_description = attrs.parameter_descriptions.get("return", "")
         response_types = attrs.response_types.copy()
         if return_type or len(response_types) == 0:
             response_types[attrs.success_code] = ResponseType(
                 type=return_type,
+                type_description=type_description,
                 description="success"
             )
         return response_types

transmute_core/http_parameters/param_set.py

@@ -7,7 +7,7 @@
 class Param(object):
     """ a single parameter object. """
     argument_name = attr.ib()
-    description = attr.ib(default=None)
+    description = attr.ib(default="")
     # the actual argument object. this gets populated later.
     arginfo = attr.ib(default=None)
 

transmute_core/http_parameters/swagger.py

@@ -11,6 +11,7 @@ def get_swagger_parameters(parameters, context):
         arginfo = param.arginfo
         params = {
             "name": name,
+            "description": param.description,
             "required": arginfo.default is NoDefault,
             "collectionFormat": "multi"
         }
@@ -23,6 +24,7 @@ def get_swagger_parameters(parameters, context):
         arginfo = param.arginfo
         params = {
             "name": name,
+            "description": param.description,
             "required": arginfo.default is NoDefault
         }
         params.update(
@@ -38,6 +40,7 @@ def get_swagger_parameters(parameters, context):
         arginfo = param.arginfo
         params = {
             "name": name,
+            "description": param.description,
             "required": arginfo.default is NoDefault
         }
         params.update(
@@ -50,8 +53,10 @@ def get_swagger_parameters(parameters, context):
 
 def _build_body_schema(serializer, body_parameters):
     """ body is built differently, since it's a single argument no matter what. """
+    description = ""
     if isinstance(body_parameters, Param):
         schema = serializer.to_json_schema(body_parameters.arginfo.type)
+        description = body_parameters.description
         required = True
     else:
         if len(body_parameters) == 0:
@@ -61,6 +66,7 @@ def _build_body_schema(serializer, body_parameters):
         for name, param in body_parameters.items():
             arginfo = param.arginfo
             body_properties[name] = serializer.to_json_schema(arginfo.type)
+            body_properties[name]["description"] = param.description
             if arginfo.default is NoDefault:
                 required.add(name)
         schema = {
@@ -71,6 +77,7 @@ def _build_body_schema(serializer, body_parameters):
         required = len(required) > 0
     return BodyParameter({
         "name": "body",
+        "description": description,
         "required": required,
         "schema": schema
     })

transmute_core/tests/http_parameters/test_swagger.py

@@ -11,6 +11,7 @@ def test_post_schema_swagger(parameter_post_schema, context):
         "in": "body",
         "name": "body",
         "required": True,
+        "description": "",
         "schema": {
             "type": "integer"
         }
@@ -26,7 +27,8 @@ def test_header_only_schema(context):
         "in": "path",
         "name": "path",
         "required": True,
-        "type": "integer"
+        "type": "integer",
+        "description": "",
     }
 
 @pytest.mark.parametrize("inp, expected", [
@@ -40,7 +42,8 @@ def test_header_only_schema(context):
         "required": True,
         "type": "string",
         "format": "date-time",
-        "collectionFormat": "multi"
+        "collectionFormat": "multi",
+        "description": ""
      }
     ),
     (Parameters(path=ParamSet({
@@ -52,7 +55,8 @@ def test_header_only_schema(context):
         "name": "path",
         "required": True,
         "type": "string",
-        "format": "date-time"
+        "format": "date-time",
+        "description": ""
      }
     ),
     (Parameters(header=ParamSet({
@@ -64,7 +68,8 @@ def test_header_only_schema(context):
         "name": "path",
         "required": True,
         "type": "string",
-        "format": "date-time"
+        "format": "date-time",
+        "description": ""
      }
     )
 ])

transmute_core/tests/swagger/test_function.py

@@ -26,7 +26,8 @@ def test_swagger_parameters():
         "name": "query",
         "required": False,
         "type": "integer",
-        "collectionFormat": "multi"
+        "collectionFormat": "multi",
+        "description": ""
     } in params
     assert {
         "in": "body",
@@ -35,21 +36,24 @@ def test_swagger_parameters():
             "type": "object",
             "required": ["left"],
             "properties": {
-                "left": {"type": "integer"},
-                "right": {"type": "integer"}
+                "left": {"type": "integer", "description": ""},
+                "right": {"type": "integer", "description": ""}
             }
         },
         "required": True,
+        "description": ""
     } in params
     assert {
         "in": "header",
         "name": "header",
         "type": "integer",
         "required": True,
+        "description": ""
     } in params
     assert {
         "in": "path",
         "name": "path",
         "type": "integer",
         "required": True,
+        "description": ""
     } in params

transmute_core/tests/test_swagger.py

@@ -1,5 +1,8 @@
 import swagger_schema
-from transmute_core import default_context
+from transmute_core import (
+    default_context, describe, annotate,
+    TransmuteFunction
+)
 from transmute_core.swagger import (
     generate_swagger_html, get_swagger_static_root,
     SwaggerSpec
@@ -108,3 +111,36 @@ def test_swagger_get_post(transmute_func, transmute_func_post):
     spec = routes.swagger_definition()
     assert "get" in spec["paths"]["/api/v1/multiply"]
     assert "post" in spec["paths"]["/api/v1/multiply"]
+
+def test_swagger_parameter_description():
+    """
+    if parameter descriptions are added to a function, they
+    should appear in the swagger json.
+    """
+    parameter_descriptions = {
+        "left": "the left operand",
+        "right": "the right operand",
+        "header": "the header",
+        "path": "the path",
+        "return": "the result"
+    }
+
+    @describe(paths="/api/v1/adopt/{path}",
+              parameter_descriptions=parameter_descriptions,
+              header_parameters=["header"])
+    @annotate({"left": int, "right": int, "header": str,
+               "path": str, "return": int})
+    def adopt(left, right, header, path):
+        return left + right
+
+    func = TransmuteFunction(adopt)
+
+    routes = SwaggerSpec()
+    routes.add_func(func, default_context)
+    spec = routes.swagger_definition()
+
+    params = spec["paths"]["/api/v1/adopt/{path}"]["get"]["parameters"]
+    for param in spec["paths"]["/api/v1/adopt/{path}"]["get"]["parameters"]:
+        assert parameter_descriptions[param["name"]] == param["description"]
+    assert parameter_descriptions["return"] == \
+        spec["paths"]["/api/v1/adopt/{path}"]["get"]["responses"]["200"]["schema"]["description"]