Add swagger ui doc visualisation

example/example_a_flask.py

 controllers.bind(app)
 
 hapic.set_context(FlaskContext(app))
+hapic.add_documentation_view('/api-doc', 'DOC', 'Generated doc')
 print(json.dumps(hapic.generate_doc()))
 app.run(host='localhost', port=8080, debug=True)

hapic/__init__.py

 output_file = _hapic_default.output_file
 generate_doc = _hapic_default.generate_doc
 set_context = _hapic_default.set_context
+add_documentation_view = _hapic_default.add_documentation_view
 handle_exception = _hapic_default.handle_exception

hapic/context.py

     def get_response(
         self,
         # TODO BS 20171228: rename into response_content
-        response: dict,
+        response: str,
         http_code: int,
+        mimetype: str='application/json',
     ) -> typing.Any:
         raise NotImplementedError()
 
         """
         raise NotImplementedError()
 
+    def add_view(
+        self,
+        route: str,
+        http_method: str,
+        view_func: typing.Callable[..., typing.Any],
+    ) -> None:
+        """
+        This method must permit to add a view in current context
+        :param route: The route depending of framework format, ex "/foo"
+        :param http_method: HTTP method like GET, POST, etc ...
+        :param view_func: The view callable
+        """
+        raise NotImplementedError()
+
+    def serve_directory(
+        self,
+        route_prefix: str,
+        directory_path: str,
+    ) -> None:
+        """
+        Configure a path to serve a directory content
+        :param route_prefix: The base url for serve the directory, eg /static
+        :param directory_path: The file system path
+        """
+        raise NotImplementedError()
+
 
 class BaseContext(ContextInterface):
     def get_default_error_builder(self) -> ErrorBuilderInterface:

hapic/decorator.py

 # -*- coding: utf-8 -*-
+import json
+
 import functools
 import typing
 try:  # Python 3.5+
 
             processed_response = self.processor.process(response)
             prepared_response = self.context.get_response(
-                processed_response,
+                json.dumps(processed_response),
                 self.default_http_code,
             )
             return prepared_response
                 )
 
             error_response = self.context.get_response(
-                response_content,
+                json.dumps(response_content),
                 self.http_code,
             )
             return error_response

hapic/doc.py

 # -*- coding: utf-8 -*-
+import json
+
 import typing
+import yaml
 
 from apispec import APISpec
 from apispec import Path
 
         return spec.to_dict()
 
+    def save_in_file(
+        self,
+        doc_file_path: str,
+        controllers: typing.List[DecoratedController],
+        context: ContextInterface,
+        title: str='',
+        description: str='',
+    ) -> None:
+        # generate this file
+        dict_doc = self.get_doc(
+            controllers=controllers,
+            context=context,
+            title=title,
+            description=description,
+        )
+        json_doc = json.dumps(dict_doc)
+
+        # We dump then load with json to use real scalar dict.
+        # If not, yaml dump dict-like objects
+        clean_dict_doc = json.loads(json_doc)
+        yaml_doc = yaml.dump(clean_dict_doc, default_flow_style=False)
+        with open(doc_file_path, 'w+') as doc_file:
+            doc_file.write(yaml_doc)
+
 
 # TODO BS 20171109: Must take care of already existing definition names
 def generate_schema_name(schema):

hapic/ext/bottle/context.py

 
     def get_response(
         self,
-        response: dict,
+        response: str,
         http_code: int,
+        mimetype: str='application/json',
     ) -> bottle.HTTPResponse:
         return bottle.HTTPResponse(
-            body=json.dumps(response),
+            body=response,
             headers=[
-                ('Content-Type', 'application/json'),
+                ('Content-Type', mimetype),
             ],
             status=http_code,
         )

hapic/ext/flask/context.py

 from hapic.error import DefaultErrorBuilder
 from hapic.error import ErrorBuilderInterface
 from flask import Flask
+from flask import send_from_directory
 
 if typing.TYPE_CHECKING:
     from flask import Response
 
     def get_response(
         self,
-        response: dict,
+        response: str,
         http_code: int,
+        mimetype: str='application/json',
     ) -> 'Response':
         from flask import Response
         return Response(
-            response=json.dumps(response),
-            mimetype='application/json',
+            response=response,
+            mimetype=mimetype,
             status=http_code,
         )
 
     def by_pass_output_wrapping(self, response: typing.Any) -> bool:
         from flask import Response
         return isinstance(response, Response)
+
+    def add_view(
+        self,
+        route: str,
+        http_method: str,
+        view_func: typing.Callable[..., typing.Any],
+    ) -> None:
+        self.app.add_url_rule(
+            rule=route,
+            view_func=view_func,
+        )
+
+    def serve_directory(
+        self,
+        route_prefix: str,
+        directory_path: str,
+    ) -> None:
+        if not route_prefix.endswith('/'):
+            route_prefix = '{}/'.format(route_prefix)
+
+        @self.app.route(
+            route_prefix,
+            defaults={
+                'path': 'index.html',
+            }
+        )
+        @self.app.route(
+            '{}<path:path>'.format(route_prefix),
+        )
+        def api_doc(path):
+            return send_from_directory(directory_path, path)

hapic/ext/pyramid/context.py

 
     def get_response(
         self,
-        response: dict,
+        response: str,
         http_code: int,
+        mimetype: str='application/json',
     ) -> 'Response':
         from pyramid.response import Response
         return Response(
-            body=json.dumps(response),
+            body=response,
             headers=[
-                ('Content-Type', 'application/json'),
+                ('Content-Type', mimetype),
             ],
             status=http_code,
         )

hapic/hapic.py

 # -*- coding: utf-8 -*-
+import os
 import typing
 import uuid
 import functools
             title=title,
             description=description,
         )
+
+    def save_doc_in_file(
+        self,
+        file_path: str,
+        title: str='',
+        description: str='',
+    ) -> None:
+        """
+        See hapic.doc.DocGenerator#get_doc docstring
+        :param file_path: The file path to write doc in YAML format
+        :param title: Title of generated doc
+        :param description: Description of generated doc
+        """
+        self.doc_generator.save_in_file(
+            file_path,
+            controllers=self._controllers,
+            context=self.context,
+            title=title,
+            description=description,
+        )
+
+    def add_documentation_view(
+        self,
+        route: str,
+        title: str='',
+        description: str='',
+    ) -> None:
+        # Ensure "/" at end of route, else web browser will not consider it as
+        # a path
+        if not route.endswith('/'):
+            route = '{}/'.format(route)
+
+        # Add swagger directory as served static dir
+        swaggerui_path = os.path.join(
+            os.path.dirname(os.path.abspath(__file__)),
+            'static',
+            'swaggerui',
+        )
+        self.context.serve_directory(
+            route,
+            swaggerui_path,
+        )
+
+        # Generate documentation file
+        doc_page_path = os.path.join(swaggerui_path, 'spec.yml')
+        self.save_doc_in_file(doc_page_path)
+
+        # Prepare views html content
+        doc_index_path = os.path.join(swaggerui_path, 'index.html')
+        with open(doc_index_path, 'r') as doc_page:
+            doc_page_content = doc_page.read()
+        doc_page_content = doc_page_content.replace(
+            '{{ spec_uri }}',
+            'spec.yml',
+        )
+
+        # Declare the swaggerui view
+        def api_doc_view():
+            return self.context.get_response(
+                doc_page_content,
+                http_code=HTTPStatus.OK,
+                mimetype='text/html',
+            )
+
+        # Add a view to generate the html index page of swaggerui
+        self.context.add_view(
+            route=route,
+            http_method='GET',
+            view_func=api_doc_view,
+        )

hapic/static/swaggerui/index.html

+<!-- HTML for static distribution bundle build -->
+<!DOCTYPE html>
+<html lang="en">
+<head>
+  <meta charset="UTF-8">
+  <title>Swagger UI</title>
+  <link href="https://fonts.googleapis.com/css?family=Open+Sans:400,700|Source+Code+Pro:300,600|Titillium+Web:400,600,700" rel="stylesheet">
+  <link rel="stylesheet" type="text/css" href="./swagger-ui.css" >
+  <link rel="icon" type="image/png" href="./favicon-32x32.png" sizes="32x32" />
+  <link rel="icon" type="image/png" href="./favicon-16x16.png" sizes="16x16" />
+  <style>
+    html
+    {
+      box-sizing: border-box;
+      overflow: -moz-scrollbars-vertical;
+      overflow-y: scroll;
+    }
+    *,
+    *:before,
+    *:after
+    {
+      box-sizing: inherit;
+    }
+
+    body {
+      margin:0;
+      background: #fafafa;
+    }
+  </style>
+</head>
+
+<body>
+
+<svg xmlns="http://www.w3.org/2000/svg" xmlns:xlink="http://www.w3.org/1999/xlink" style="position:absolute;width:0;height:0">
+  <defs>
+    <symbol viewBox="0 0 20 20" id="unlocked">
+          <path d="M15.8 8H14V5.6C14 2.703 12.665 1 10 1 7.334 1 6 2.703 6 5.6V6h2v-.801C8 3.754 8.797 3 10 3c1.203 0 2 .754 2 2.199V8H4c-.553 0-1 .646-1 1.199V17c0 .549.428 1.139.951 1.307l1.197.387C5.672 18.861 6.55 19 7.1 19h5.8c.549 0 1.428-.139 1.951-.307l1.196-.387c.524-.167.953-.757.953-1.306V9.199C17 8.646 16.352 8 15.8 8z"></path>
+    </symbol>
+
+    <symbol viewBox="0 0 20 20" id="locked">
+      <path d="M15.8 8H14V5.6C14 2.703 12.665 1 10 1 7.334 1 6 2.703 6 5.6V8H4c-.553 0-1 .646-1 1.199V17c0 .549.428 1.139.951 1.307l1.197.387C5.672 18.861 6.55 19 7.1 19h5.8c.549 0 1.428-.139 1.951-.307l1.196-.387c.524-.167.953-.757.953-1.306V9.199C17 8.646 16.352 8 15.8 8zM12 8H8V5.199C8 3.754 8.797 3 10 3c1.203 0 2 .754 2 2.199V8z"/>
+    </symbol>
+
+    <symbol viewBox="0 0 20 20" id="close">
+      <path d="M14.348 14.849c-.469.469-1.229.469-1.697 0L10 11.819l-2.651 3.029c-.469.469-1.229.469-1.697 0-.469-.469-.469-1.229 0-1.697l2.758-3.15-2.759-3.152c-.469-.469-.469-1.228 0-1.697.469-.469 1.228-.469 1.697 0L10 8.183l2.651-3.031c.469-.469 1.228-.469 1.697 0 .469.469.469 1.229 0 1.697l-2.758 3.152 2.758 3.15c.469.469.469 1.229 0 1.698z"/>
+    </symbol>
+
+    <symbol viewBox="0 0 20 20" id="large-arrow">
+      <path d="M13.25 10L6.109 2.58c-.268-.27-.268-.707 0-.979.268-.27.701-.27.969 0l7.83 7.908c.268.271.268.709 0 .979l-7.83 7.908c-.268.271-.701.27-.969 0-.268-.269-.268-.707 0-.979L13.25 10z"/>
+    </symbol>
+
+    <symbol viewBox="0 0 20 20" id="large-arrow-down">
+      <path d="M17.418 6.109c.272-.268.709-.268.979 0s.271.701 0 .969l-7.908 7.83c-.27.268-.707.268-.979 0l-7.908-7.83c-.27-.268-.27-.701 0-.969.271-.268.709-.268.979 0L10 13.25l7.418-7.141z"/>
+    </symbol>
+
+
+    <symbol viewBox="0 0 24 24" id="jump-to">
+      <path d="M19 7v4H5.83l3.58-3.59L8 6l-6 6 6 6 1.41-1.41L5.83 13H21V7z"/>
+    </symbol>
+
+    <symbol viewBox="0 0 24 24" id="expand">
+      <path d="M10 18h4v-2h-4v2zM3 6v2h18V6H3zm3 7h12v-2H6v2z"/>
+    </symbol>
+
+  </defs>
+</svg>
+
+<div id="swagger-ui"></div>
+
+<script src="./swagger-ui-bundle.js"> </script>
+<script src="./swagger-ui-standalone-preset.js"> </script>
+<script>
+window.onload = function() {
+  
+  // Build a system
+  const ui = SwaggerUIBundle({
+    url: "{{ spec_uri }}",
+    dom_id: '#swagger-ui',
+    deepLinking: true,
+    presets: [
+      SwaggerUIBundle.presets.apis,
+      SwaggerUIStandalonePreset
+    ],
+    plugins: [
+      SwaggerUIBundle.plugins.DownloadUrl
+    ],
+    layout: "StandaloneLayout"
+  })
+
+  window.ui = ui
+}
+</script>
+</body>
+
+</html>

hapic/static/swaggerui/spec.yml

+definitions:
+  DefaultErrorBuilder:
+    properties:
+      code:
+        type: string
+        x-nullable: true
+      details:
+        type: object
+      message:
+        type: string
+    required:
+    - message
+    type: object
+  HelloJsonSchema:
+    properties:
+      color:
+        minLength: 3
+        type: string
+    required:
+    - color
+    type: object
+  HelloResponseSchema:
+    properties:
+      color:
+        type: string
+      name:
+        type: string
+      sentence:
+        type: string
+    required:
+    - name
+    - sentence
+    type: object
+info:
+  description: ''
+  title: ''
+  version: 1.0.0
+parameters: {}
+paths:
+  /hello/{name}:
+    get:
+      description: "my endpoint hello\n        ---\n        get:\n            description:\
+        \ my description\n            parameters:\n                - in: \"path\"\n\
+        \                  description: \"hello\"\n                  name: \"name\"\
+        \n                  type: \"string\"\n            responses:\n           \
+        \     200:\n                    description: A pet to be returned\n      \
+        \              schema: HelloResponseSchema"
+      parameters:
+      - in: path
+        name: name
+        required: true
+        type: string
+      - in: query
+        name: alive
+        required: false
+        type: boolean
+      responses:
+        '200':
+          description: '200'
+          schema:
+            $ref: '#/definitions/HelloResponseSchema'
+        '400':
+          description: '400'
+          schema:
+            $ref: '#/definitions/DefaultErrorBuilder'
+    post:
+      parameters:
+      - in: body
+        name: body
+        schema:
+          $ref: '#/definitions/HelloJsonSchema'
+      - in: path
+        name: name
+        required: true
+        type: string
+      responses:
+        '200':
+          description: '200'
+          schema:
+            $ref: '#/definitions/HelloResponseSchema'
+  /hello3/{name}:
+    get:
+      parameters:
+      - in: path
+        name: name
+        required: true
+        type: string
+      responses:
+        '200':
+          description: '200'
+          schema:
+            $ref: '#/definitions/HelloResponseSchema'
+swagger: '2.0'
+tags: []

tests/base.py

 
     def get_response(
         self,
-        response: dict,
+        response: str,
         http_code: int,
+        mimetype: str='application/json',
     ) -> typing.Any:
         return {
             'original_response': response,