generation swagger doc: minimal working version

example.py

@@ -20,6 +20,12 @@ class HelloPathSchema(marshmallow.Schema):
     )
 
 
+class HelloQuerySchema(marshmallow.Schema):
+    alive = marshmallow.fields.Boolean(
+        required=False,
+    )
+
+
 class HelloJsonSchema(marshmallow.Schema):
     color =marshmallow.fields.String(
         required=True,

example_a.py

@@ -1,10 +1,14 @@
 # -*- coding: utf-8 -*-
+import json
 from http import HTTPStatus
 
 import bottle
+import time
+import yaml
+
 import hapic
 from example import HelloResponseSchema, HelloPathSchema, HelloJsonSchema, \
-    ErrorResponseSchema
+    ErrorResponseSchema, HelloQuerySchema
 from hapic.data import HapicData
 
 app = bottle.Bottle()
@@ -20,8 +24,24 @@ def bob(f):
 # @hapic.ext.bottle.bottle_context()
 @hapic.handle_exception(ZeroDivisionError, http_code=HTTPStatus.BAD_REQUEST)
 @hapic.input_path(HelloPathSchema())
+@hapic.input_query(HelloQuerySchema())
 @hapic.output_body(HelloResponseSchema())
 def hello(name: str, hapic_data: HapicData):
+    """
+    my endpoint hello
+    ---
+    get:
+        description: my description
+        parameters:
+            - in: "path"
+              description: "hello"
+              name: "name"
+              type: "string"
+        responses:
+            200:
+                description: A pet to be returned
+                schema: HelloResponseSchema
+    """
     if name == 'zero':
         raise ZeroDivisionError('Don\'t call him zero !')
 
@@ -51,6 +71,7 @@ kwargs = {'validated_data': {'name': 'bob'}, 'name': 'bob'}
 @hapic.with_api_doc()
 # @hapic.ext.bottle.bottle_context()
 # @hapic.error_schema(ErrorResponseSchema())
+@hapic.input_path(HelloPathSchema())
 @hapic.output_body(HelloResponseSchema())
 def hello3(name: str):
     return {
@@ -60,8 +81,20 @@ def hello3(name: str):
 
 
 app.route('/hello/<name>', callback=hello)
-app.route('/hello2/<name>', callback=hello2, method='POST')
+app.route('/hello/<name>', callback=hello2, method='POST')
 app.route('/hello3/<name>', callback=hello3)
 
-hapic.generate_doc(app)
+# time.sleep(1)
+# s = hapic.generate_doc(app)
+# ss = json.loads(json.dumps(s))
+# for path in ss['paths']:
+#     for method in ss['paths'][path]:
+#         for response_code in ss['paths'][path][method]['responses']:
+#             ss['paths'][path][method]['responses'][int(response_code)] = ss['paths'][path][method]['responses'][response_code]
+#             del ss['paths'][path][method]['responses'][int(response_code)]
+# print(yaml.dump(ss, default_flow_style=False))
+# time.sleep(1)
+
+print(json.dumps(hapic.generate_doc(app)))
+
 app.run(host='localhost', port=8080, debug=True)

hapic/context.py

@@ -29,6 +29,7 @@ class ContextInterface(object):
         raise NotImplementedError()
 
 
+# TODO: In extension
 class BottleContext(ContextInterface):
     def get_request_parameters(self, *args, **kwargs) -> RequestParameters:
         return RequestParameters(

hapic/decorator.py

@@ -1,4 +1,5 @@
 # -*- coding: utf-8 -*-
+import functools
 import typing
 from http import HTTPStatus
 
@@ -35,7 +36,7 @@ class ControllerWrapper(object):
             response = self._execute_wrapped_function(func, args, kwargs)
             new_response = self.after_wrapped_function(response)
             return new_response
-        return wrapper
+        return functools.update_wrapper(wrapper, func)
 
     def _execute_wrapped_function(
         self,

hapic/description.py

@@ -27,7 +27,8 @@ class InputHeadersDescription(Description):
 
 
 class InputFormsDescription(Description):
-    pass
+    def __init__(self, wrapper: 'ControllerWrapper') -> None:
+        self.wrapper = wrapper
 
 
 class OutputBodyDescription(Description):

hapic/doc.py

@@ -0,0 +1,171 @@
+# -*- coding: utf-8 -*-
+import re
+import typing
+
+import bottle
+from apispec import APISpec, Path
+from apispec.ext.marshmallow.swagger import schema2jsonschema
+
+from hapic.decorator import DecoratedController
+
+
+# Bottle regular expression to locate url parameters
+from hapic.description import ControllerDescription
+
+BOTTLE_RE_PATH_URL = re.compile(r'<(?:[^:<>]+:)?([^<>]+)>')
+
+
+def bottle_route_for_view(reference, app):
+    for route in app.routes:
+        if route.callback == reference:
+            return route
+    # TODO: specialize exception
+    raise Exception('Not found')
+
+
+def bottle_generate_operations(
+    spec,
+    bottle_route: bottle.Route,
+    description: ControllerDescription,
+):
+    method_operations = dict()
+
+    # schema based
+    if description.input_body:
+        schema_class = type(description.input_body.wrapper.processor.schema)
+        method_operations.setdefault('parameters', []).append({
+            'in': 'body',
+            'name': 'body',
+            'schema': {
+                '$ref': '#/definitions/{}'.format(schema_class.__name__)
+            }
+        })
+
+    if description.output_body:
+        schema_class = type(description.output_body.wrapper.processor.schema)
+        method_operations.setdefault('responses', {})\
+            [int(description.output_body.wrapper.default_http_code)] = {
+                'description': str(description.output_body.wrapper.default_http_code),  # nopep8
+                'schema': {
+                    '$ref': '#/definitions/{}'.format(schema_class.__name__)
+                }
+            }
+
+    if description.errors:
+        for error in description.errors:
+            method_operations.setdefault('responses', {})\
+                [int(error.wrapper.http_code)] = {
+                    'description': str(error.wrapper.http_code),
+                }
+
+    # jsonschema based
+    if description.input_path:
+        schema_class = type(description.input_path.wrapper.processor.schema)
+        jsonschema = schema2jsonschema(schema_class, spec=spec)
+        for name, schema in jsonschema.get('properties', {}).items():
+            method_operations.setdefault('parameters', []).append({
+                'in': 'path',
+                'name': name,
+                'required': name in jsonschema.get('required', []),
+                'type': schema['type']
+            })
+
+    if description.input_query:
+        schema_class = type(description.input_query.wrapper.processor.schema)
+        jsonschema = schema2jsonschema(schema_class, spec=spec)
+        for name, schema in jsonschema.get('properties', {}).items():
+            method_operations.setdefault('parameters', []).append({
+                'in': 'query',
+                'name': name,
+                'required': name in jsonschema.get('required', []),
+                'type': schema['type']
+            })
+
+    operations = {
+        bottle_route.method.lower(): method_operations,
+    }
+
+    return operations
+
+
+class DocGenerator(object):
+    def get_doc(
+        self,
+        controllers: typing.List[DecoratedController],
+        app,
+    ) -> dict:
+        # TODO: Découper
+        # TODO: bottle specific code !
+        if not app:
+            app = bottle.default_app()
+        else:
+            bottle.default_app.push(app)
+        flatten = lambda l: [item for sublist in l for item in sublist]
+
+        spec = APISpec(
+            title='Swagger Petstore',
+            version='1.0.0',
+            plugins=[
+                'apispec.ext.bottle',
+                'apispec.ext.marshmallow',
+            ],
+        )
+
+        schemas = []
+        # parse schemas
+        for controller in controllers:
+            description = controller.description
+
+            if description.input_body:
+                schemas.append(type(
+                    description.input_body.wrapper.processor.schema
+                ))
+
+            if description.input_forms:
+                schemas.append(type(
+                    description.input_forms.wrapper.processor.schema
+                ))
+
+            if description.output_body:
+                schemas.append(type(
+                    description.output_body.wrapper.processor.schema
+                ))
+
+        for schema in set(schemas):
+            spec.definition(schema.__name__, schema=schema)
+
+        # add views
+        # with app.test_request_context():
+        paths = {}
+        for controller in controllers:
+            bottle_route = bottle_route_for_view(controller.reference, app)
+            swagger_path = BOTTLE_RE_PATH_URL.sub(r'{\1}', bottle_route.rule)
+
+            operations = bottle_generate_operations(
+                spec,
+                bottle_route,
+                controller.description,
+            )
+
+            path = Path(path=swagger_path, operations=operations)
+
+            if swagger_path in paths:
+                paths[swagger_path].update(path)
+            else:
+                paths[swagger_path] = path
+
+            spec.add_path(path)
+
+        return spec.to_dict()
+
+        # route_by_callbacks = []
+        # routes = flatten(app.router.dyna_routes.values())
+        # for path, path_regex, route, func_ in routes:
+        #     route_by_callbacks.append(route.callback)
+        #
+        # for description in self._controllers:
+        #     for path, path_regex, route, func_ in routes:
+        #         if route.callback == description.reference:
+        #             # TODO: use description to feed apispec
+        #             print(route.method, path, description)
+        #             continue

hapic/hapic.py

@@ -1,11 +1,8 @@
 # -*- coding: utf-8 -*-
 import typing
 from http import HTTPStatus
-
-import bottle
 import functools
 
-# CHANGE
 import marshmallow
 
 from hapic.buffer import DecorationBuffer
@@ -18,16 +15,16 @@ from hapic.decorator import InputPathControllerWrapper
 from hapic.decorator import InputQueryControllerWrapper
 from hapic.decorator import OutputBodyControllerWrapper
 from hapic.decorator import OutputHeadersControllerWrapper
-from hapic.description import InputBodyDescription
+from hapic.description import InputBodyDescription, ErrorDescription
 from hapic.description import InputFormsDescription
 from hapic.description import InputHeadersDescription
 from hapic.description import InputPathDescription
 from hapic.description import InputQueryDescription
 from hapic.description import OutputBodyDescription
 from hapic.description import OutputHeadersDescription
-from hapic.processor import ProcessorInterface, MarshmallowInputProcessor
-
-flatten = lambda l: [item for sublist in l for item in sublist]
+from hapic.doc import DocGenerator
+from hapic.processor import ProcessorInterface
+from hapic.processor import MarshmallowInputProcessor
 
 # TODO: Gérer les erreurs de schema
 # TODO: Gérer les cas ou c'est une liste la réponse (items, item_nb)
@@ -47,7 +44,8 @@ _default_global_error_schema = ErrorResponseSchema()
 class Hapic(object):
     def __init__(self):
         self._buffer = DecorationBuffer()
-        self._controllers = []
+        self._controllers = []  # type: typing.List[DecoratedController]
+        # TODO: Permettre la surcharge des classes utilisés ci-dessous
 
     def with_api_doc(self):
         def decorator(func):
@@ -250,22 +248,11 @@ class Hapic(object):
         )
 
         def decorator(func):
-            self._buffer.input_forms = InputFormsDescription(decoration)
+            self._buffer.errors.append(ErrorDescription(decoration))
             return decoration.get_wrapper(func)
         return decorator
 
     def generate_doc(self, app=None):
         # TODO @Damien bottle specific code !
-        app = app or bottle.default_app()
-
-        route_by_callbacks = []
-        routes = flatten(app.router.dyna_routes.values())
-        for path, path_regex, route, func_ in routes:
-            route_by_callbacks.append(route.callback)
-
-        for description in self._controllers:
-            for path, path_regex, route, func_ in routes:
-                if route.callback == description.reference:
-                    # TODO: use description to feed apispec
-                    print(route.method, path, description)
-                    continue
+        doc_generator = DocGenerator()
+        return doc_generator.get_doc(self._controllers, app)

setup.py

@@ -11,6 +11,7 @@ install_requires = [
     # TODO: marshmallow an extension too ?
     'bottle',
     'marshmallow',
+    'apispec',
 ]
 tests_require = [
     'pytest',