add resource __doc__ support

docs/index.rst

@@ -16,8 +16,7 @@ Welcome to the **RestIt** documentation.
 Python HTTP REST library including OOP-readiness and Open-API generation
 
 .. toctree::
-   :titlesonly:
-   :includehidden:
+   :maxdepth: 4
 
    installation
    quickstart

docs/quickstart.rst

@@ -1,8 +1,8 @@
 Quickstart
-==========
+**********
 
 A Minimal Application
----------------------
+=====================
 
 To get started with RestIt we can use the following code snippet:
 
@@ -29,8 +29,8 @@ One of the key aspects of *REST* and the *RestIt* library are *Resources*. Since
 *URI*, in our Python code we assign it using the :func:`~restit.decorator.path` decorator.
 
 
-Serve Swagger/OpenApi Documentation
---------------------------------------
+Swagger/OpenApi Documentation
+=============================
 
 To get your HTTP app serving an *OpenApi* documentation, you have to create an instance of
 :class:`~restit.open_api.OpenApiDocumentation` and pass it to your :class:`~restit.RestItApp` constructor.
@@ -55,3 +55,39 @@ documentation.
     Since we did not yet provide any information about our API we do not see too much in the *OpenApi* documentation yet.
 
 
+More OpenApi Documentation Details
+------------------------------------
+
+Request Details
+^^^^^^^^^^^^^^^
+
+A description for the request method is always a good starting point and so we are adding a simple doc string to our
+``get`` method:
+
+.. code-block:: python
+
+    @path("/")
+    class IndexResource(Resource):
+        def get(self, request: Request) -> Response:
+            """This is a super get method.
+
+            It takes a request and responds with a text.
+            """
+            return Response("Hello from index.")
+
+
+The doc string then will be used to generate the `summary and description <https://swagger.io/specification/#operationObject>`_  fields.
+
+
+Query Parameters
+""""""""""""""""
+
+Path Parameters
+"""""""""""""""
+
+Request Body
+""""""""""""
+
+
+Response Details
+^^^^^^^^^^^^^^^^

restit/open_api/open_api_documentation.py

@@ -43,7 +43,11 @@ def _generate_paths(self, root_spec: dict):
     def _add_resource(self, paths: dict, resource: Resource, root_spec: dict):
         path, inferred_path_parameters = \
             self._infer_path_params_and_open_api_path_syntax(resource.__request_mapping__)
-        paths[path] = {}
+        summary, description = self._get_summary_and_description_from_doc(resource.__doc__)
+        paths[path] = {
+            "summary": summary,
+            "description": description
+        }
         for method_name, method_object in self._get_allowed_resource_methods(resource).items():
             paths[path][method_name] = {
                 "responses": {},

test/restit/open_api/open_api_spec_test.py

@@ -23,6 +23,11 @@ class MyRequestBodySchema(Schema):
 
 @path("/path")
 class FirstResource(Resource):
+    """First resource summary
+
+    Super description.
+    """
+
     @query_parameter("param1", description="A query parameter", field_type=fields.Integer(default=10))
     def get(self, request: Request, **path_params) -> Response:
         """This is a summary.
@@ -112,6 +117,9 @@ def test_generate_spec(self):
         self.assertEqual("3.0.0", open_api_dict["openapi"])
 
         paths_path = open_api_dict["paths"]["/path"]
+        self.assertEqual("First resource summary", paths_path["summary"])
+        self.assertEqual("Super description.", paths_path["description"])
+
         self.assertEqual({
             'responses': {},
             'parameters': [{