Parse extended operation description

apistrap/aiohttp.py

@@ -403,9 +403,10 @@ def _extract_operation_spec(self, route: AbstractRoute) -> dict:
         handler = getattr(route.handler, self.SYNTHETIC_WRAPPER_ATTR, route.handler)
 
         specs_dict = deepcopy(getattr(handler, "specs_dict", {"parameters": [], "responses": {}}))
-        specs_dict["summary"] = self._summary_from_docblock(handler.__doc__)
         specs_dict["operationId"] = snake_to_camel(handler.__name__)
 
+        self._descriptions_from_docblock(handler.__doc__, specs_dict)
+
         signature = inspect.signature(handler)
         param_doc = self._parameters_from_docblock(handler.__doc__)
 

apistrap/extension.py

@@ -160,20 +160,21 @@ def _is_route_ignored(self, method: str, handler) -> bool:
     def _parameter_annotation_to_openapi_type(self, annotation):
         return self.PARAMETER_TYPE_MAP.get(annotation, "string")
 
-    def _summary_from_docblock(self, docblock: Optional[str]) -> str:
-        if docblock is None:
-            return ""
-
-        return parse_doc(docblock).short_description
-
     def _parameters_from_docblock(self, docblock: Optional[str]) -> Dict[str, str]:
-        if docblock is None:
-            return {}
 
         return {
             param.arg_name: param.description for param in parse_doc(docblock).params if param.description.strip() != ""
         }
 
+    def _descriptions_from_docblock(self, docblock: Optional[str], target: dict):
+        if docblock is None:
+            return {}
+
+        parsed = parse_doc(docblock)
+
+        target["summary"] = parsed.short_description
+        target["description"] = parsed.long_description
+
     ############################
     # Configuration properties #
     ############################

apistrap/flask.py

@@ -160,7 +160,9 @@ def _extract_operation_specs(self, handler):
         """
 
         specs_dict = deepcopy(getattr(handler, "specs_dict", {"parameters": [], "responses": {}}))
-        specs_dict["summary"] = self._summary_from_docblock(handler.__doc__)
+
+        self._descriptions_from_docblock(handler.__doc__, specs_dict)
+
         specs_dict["operationId"] = snake_to_camel(handler.__name__)
 
         signature = inspect.signature(handler)

tests/test_aiohttp_docblocks.py

@@ -28,6 +28,14 @@ async def view(param_a: str, param_b: int):
             "b": param_b
         }))
 
+    @routes.get('/extended')
+    async def view_extended():
+        """
+        A summary.
+
+        An extended description.
+        """
+
     app.add_routes(routes)
 
     yield app
@@ -57,3 +65,15 @@ async def test_parameters_from_docblock(app_with_params_as_args, aiohttp_initial
 
     assert param_a["description"] == "Parameter A"
     assert param_b["description"] == "Parameter B"
+
+
+async def test_extended_description_from_docblock(app_with_params_as_args, aiohttp_initialized_client):
+    client = await aiohttp_initialized_client(app_with_params_as_args)
+    response = await client.get("/spec.json")
+
+    assert response.status == 200
+    data = await response.json()
+    path = data["paths"]["/extended"]["get"]
+
+    assert path["summary"] == "A summary."
+    assert path["description"] == "An extended description."

tests/test_flask_docblocks.py

@@ -18,6 +18,14 @@ def view(param_a: str, param_b: int):
             "b": param_b
         })
 
+    @app.route('/extended', methods=["get"])
+    def view_extended():
+        """
+        A summary.
+
+        An extended description.
+        """
+
     yield app
 
 
@@ -41,3 +49,13 @@ def test_parameters_from_docblock(app_with_params_as_args, client):
 
     assert param_a["description"] == "Parameter A"
     assert param_b["description"] == "Parameter B"
+
+
+def test_extended_description_from_docblock(app_with_params_as_args, client):
+    response = client.get("/spec.json")
+
+    assert response.status_code == 200
+    path = response.json["paths"]["/extended"]["get"]
+
+    assert path["summary"] == "A summary."
+    assert path["description"] == "An extended description."