switch acquiring of swagger docs for payload from docstrings to funct…

…ion return instead

pfunk/utils/swagger.py

@@ -163,6 +163,7 @@ def get_operations(self, col: Collection):
         ```
         """
         for view in col.collection_views:
+            v = view()
             route = view.url(col)
             rule = route.rule
             methods = route.methods
@@ -211,17 +212,13 @@ def get_operations(self, col: Collection):
                     )
                     params.append(path_params)
 
-                # Acquire payload of the view from the View's docstring
-                # where to cut the docstrings to use the definition for the payload of the view
-                oas_str_split = '[OAS]\n'
-                view_docs = view.__doc__
-                view_payload = None
-                if (view_docs and len(view_docs.split(oas_str_split)) > 1):
-                    view_payload = view_docs.split(oas_str_split)[1]
+                # Acquire payload of the view from the View's `_payload_docs`
+                view_payload = view()._payload_docs()
 
                 # Construct payload for swagger generation
+                # TODO: support referencing of models
                 if view_payload:
-                    for field in json.loads(view_payload).get('data'):
+                    for field in view_payload.get('data'):
                         param = sw.Parameter(
                             name=field.get('name'),
                             _type=field.get('type'),
@@ -232,17 +229,16 @@ def get_operations(self, col: Collection):
                         )
                         params.append(param)
 
-                docs_description = view_docs if not len(view_docs.split(
-                    oas_str_split)) > 1 else view_docs.split(oas_str_split)[0]
                 consumes = ['application/json',
                             'application/x-www-form-urlencoded']
                 produces = ['application/json',
                             'application/x-www-form-urlencoded']
+                view_docs = view.__doc__
                 if params:
                     op = sw.Operation(
                         http_method=method.lower(),
                         summary=f'({method}) -> {col.__class__.__name__}',
-                        description=docs_description,
+                        description=view_docs,
                         responses=responses,
                         consumes=consumes,
                         produces=produces,
@@ -251,7 +247,7 @@ def get_operations(self, col: Collection):
                     op = sw.Operation(
                         http_method=method.lower(),
                         summary=f'({method}) -> {col.__class__.__name__}',
-                        description=docs_description,
+                        description=view_docs,
                         responses=responses,
                         consumes=consumes,
                         produces=produces)

pfunk/web/views/json.py

@@ -25,6 +25,29 @@ def get_response(self):
             headers=self.get_headers()
         )
 
+    def _payload_docs(self):
+        """ Used in defining payload parameters for the view. 
+        
+            Should return a dict that has the fields of a swagger parameter e.g.
+            {"data": [
+                {
+                    "name":"name",
+                    "in":"formData",
+                    "description":"name of the pet",
+                    "required": true,
+                    "type": "string"
+                },
+                {
+                    "name": "status",
+                    "in": "formData",
+                    "description": "status of the pet",
+                    "required":true,
+                    "type":"string"
+                }
+            ]}
+        """
+        return {}
+
 
 class CreateView(UpdateMixin, ActionMixin, JSONView):
     """ Define a `Create` view that allows `creation` of an entity in the collection """
@@ -34,7 +57,8 @@ class CreateView(UpdateMixin, ActionMixin, JSONView):
 
     def get_query(self):
         """ Entity created in a collection """
-        obj = self.collection.create(**self.get_query_kwargs(), _token=self.request.token)
+        obj = self.collection.create(
+            **self.get_query_kwargs(), _token=self.request.token)
         return obj
 
     def get_m2m_kwargs(self, obj):
@@ -50,7 +74,8 @@ def get_m2m_kwargs(self, obj):
 
         """
         data = self.request.get_json()
-        fields = self.collection.get_foreign_fields_by_type('pfunk.fields.ManyToManyField')
+        fields = self.collection.get_foreign_fields_by_type(
+            'pfunk.fields.ManyToManyField')
         for k, v in fields.items():
             current_value = data.get(k)
             col = v.get('foreign_class')()
@@ -70,7 +95,8 @@ class UpdateView(UpdateMixin, IDMixin, JSONView):
 
     def get_query(self):
         """ Entity in collection updated by an ID """
-        obj = self.collection.get(self.request.kwargs.get('id'), _token=self.request.token)
+        obj = self.collection.get(self.request.kwargs.get(
+            'id'), _token=self.request.token)
         obj._data.update(self.get_query_kwargs())
         obj.save()
         return obj
@@ -102,4 +128,4 @@ class ListView(QuerysetMixin, ActionMixin, JSONView):
 
 
 class GraphQLView(HTTPView):
-    pass
+    pass