[routers] docstring is mandator in route methods. YAML is used for markup

halfapi/lib/domain.py

@@ -172,9 +172,9 @@ def gen_routes(m_router: ModuleType,
 
 
 def gen_router_routes(m_router: ModuleType, path: List[str]) -> \
-    Iterator[Tuple[str, str, Coroutine, List]]:
+    Iterator[Tuple[str, str, ModuleType, Coroutine, List]]:
     """
-    Recursive generatore that parses a router (or a subrouter)
+    Recursive generator that parses a router (or a subrouter)
     and yields from gen_routes
 
     Parameters:
@@ -184,8 +184,10 @@ def gen_router_routes(m_router: ModuleType, path: List[str]) -> \
 
     Yields:
 
-        (str, str, Coroutine, List): A tuple containing the path, verb,
-            function and parameters of the route
+        (str, str, ModuleType, Coroutine, List): A tuple containing the path, verb,
+            router module, function reference and parameters of the route.
+            Function and parameters are yielded from then gen_routes function,
+            that decorates the endpoint function.
     """
 
     for subpath, params in read_router(m_router).items():

halfapi/lib/routes.py

@@ -122,10 +122,23 @@ def api_routes(m_dom: ModuleType) -> Tuple[Dict, Dict]:
         return l_params
 
     d_res = {}
-    for path, verb, _, _, params in gen_router_routes(m_dom, []):
-        if path not in d_res:
-            d_res[path] = {}
-        d_res[path][verb] = str_acl(params)
+    for path, verb, m_router, fct, params in gen_router_routes(m_dom, []):
+        try:
+            if path not in d_res:
+                d_res[path] = {}
+
+            d_res[path][verb] = {
+                'docs': yaml.load(fct.__doc__, Loader=yaml.FullLoader),
+                'acls': str_acl(params)
+            }
+        except Exception as exc:
+            logger.error("""Error in route generation
+                path:%s
+                verb:%s
+                router:%s
+                fct:%s
+                params:%s """, path, verb, m_router, fct, params)
+            raise exc
 
     return d_res, d_acls
 

tests/dummy_domain/routers/abc/alphabet/TEST_uuid/__init__.py

@@ -8,16 +8,36 @@ ACLS = {
 }
 
 def get(test):
+    """
+    description:
+        returns the path parameter
+    """
     return str(test)
 
 def post(test):
+    """
+    description:
+        returns the path parameter
+    """
     return str(test)
 
 def patch(test):
+    """
+    description:
+        returns the path parameter
+    """
     return str(test)
 
 def put(test):
+    """
+    description:
+        returns the path parameter
+    """
     return str(test)
 
 def delete(test):
+    """
+    description:
+        returns the path parameter
+    """
     return str(test)

tests/dummy_domain/routers/abc/pinnochio/__init__.py

@@ -3,4 +3,8 @@ ACLS = {
     'GET' : [{'acl':acl.public}]
 }
 def get():
+    """
+    description:
+        Not implemented
+    """
     raise NotImplementedError

tests/dummy_domain/routers/config/__init__.py

@@ -6,5 +6,9 @@ ACLS = {
 }
 
 def get(halfapi):
+    """
+    description:
+        returns the configuration of the domain
+    """
     logger.error('%s', halfapi)
     return halfapi['config']

tests/test_lib_routes.py

@@ -1,5 +1,5 @@
 from starlette.routing import Route
-from halfapi.lib.routes import gen_starlette_routes
+from halfapi.lib.routes import gen_starlette_routes, api_routes, gen_router_routes
 
 def test_gen_starlette_routes():
     from .dummy_domain import routers
@@ -7,3 +7,25 @@ def test_gen_starlette_routes():
         'dummy_domain': routers }):
 
         assert isinstance(route, Route)
+
+def test_api_routes():
+    from . import dummy_domain
+    d_res, d_acls = api_routes(dummy_domain)
+    assert isinstance(d_res, dict)
+    assert isinstance(d_acls, dict)
+
+    yielded = False
+
+    for path, verb, m_router, fct, params in gen_router_routes(dummy_domain, []):
+        if not yielded:
+            yielded = True
+
+        assert path in d_res
+        assert verb in d_res[path]
+        assert 'docs' in d_res[path][verb]
+        assert 'acls' in d_res[path][verb]
+        assert isinstance(d_res[path][verb]['docs'], dict)
+        assert isinstance(d_res[path][verb]['acls'], list)
+        assert len(d_res[path][verb]['acls']) == len(params)
+
+    assert yielded is True

tests/test_lib_schemas.py

@@ -41,4 +41,4 @@ def test_get_api_dummy_domain_routes(application_domain, routers):
     assert 'abc/alphabet' in d_r
     assert 'GET' in d_r['abc/alphabet']
     assert len(d_r['abc/alphabet']['GET']) > 0
-    assert 'acl' in d_r['abc/alphabet']['GET'][0]
+    assert 'acls' in d_r['abc/alphabet']['GET']