Merge pull request #16 from deginner/master

templates and command line interface

Author: atlithorn

README.md

@@ -100,6 +100,27 @@ def spec():
 
 Swagger-UI is the reason we embarked on this mission to begin with, flask-swagger does not however include Swagger-UI. Simply follow the awesome documentation over at https://github.com/swagger-api/swagger-ui and point your [swaggerUi.url](https://github.com/swagger-api/swagger-ui#swaggerui) to your new flask-swagger endpoint and enjoy.
 
+## flaskswagger Command
+This package now comes with a very simple command line interface: flaskswagger. This command can be used to build and update swagger specs for your flask apps from the command line or at build time.
+
+```
+flaskswagger -h
+usage: flaskswagger [-h] [--template TEMPLATE] [--out-dir OUT_DIR] app
+
+positional arguments:
+  app                  the flask app to swaggerify
+
+optional arguments:
+  -h, --help           show this help message and exit
+  --template TEMPLATE  template spec to start with
+  --out-dir OUT_DIR    the directory to output to
+```
+
+For example, this can be used to build a swagger spec which can be served from your static directory. In the example below, we use the manually created swagger.json.manual as a template, and output to the `static/` directory.
+
+```
+flaskswagger server:app --template static/swagger.json.manual --out-dir static/
+```
 
 Acknowledgements
 

build_swagger_spec.py

@@ -0,0 +1,29 @@
+import argparse
+import json
+import pkg_resources
+from flask_swagger import swagger
+
+parser = argparse.ArgumentParser()
+parser.add_argument('app', help='the flask app to swaggerify')
+#parser.add_argument('--definitions', help='json definitions file')
+parser.add_argument('--template', help='template spec to start with')
+parser.add_argument('--out-dir', default=None, help='the directory to output to')
+args = parser.parse_args()
+
+def run():
+    template = args.template
+    app = pkg_resources.EntryPoint.parse("x=%s" % args.app).load(False)
+    if template is not None:
+        with open(template, 'r') as f:
+            spec = swagger(app, template=json.loads(f.read()))
+    else:
+        spec = swagger(app)
+    if args.out_dir is None:
+        print json.dumps(spec, indent=4)
+    else:
+        with open("%s/swagger.json" % args.out_dir, 'w') as f:
+            f.write(json.dumps(spec, indent=4))
+            f.close()
+
+run()
+

flask_swagger.py

@@ -12,6 +12,7 @@
 
 from collections import defaultdict
 
+
 def _sanitize(comment):
     return comment.replace('\n', '<br/>') if comment else comment
 
@@ -87,7 +88,7 @@ def _extract_array_defs(source):
     return defs
 
 
-def swagger(app, process_doc=_sanitize):
+def swagger(app, process_doc=_sanitize, template=None):
     """
     Call this from an @app.route method like this
     @app.route('/spec.json')
@@ -103,8 +104,8 @@ def spec():
 
     Keyword arguments:
     process_doc -- text sanitization method, the default simply replaces \n with <br>
+    template -- The spec to start with and update as flask-swagger finds paths.
     """
-
     output = {
         "swagger": "2.0",
         "info": {
@@ -114,6 +115,17 @@ def spec():
         "paths": defaultdict(dict),
         "definitions": defaultdict(dict)
     }
+    # set defaults from template
+    if template is not None:
+        for tkey, tval in template.items():
+            if tkey == 'definitions':
+                for k, v in tval.items():
+                    output['definitions'][k] = v
+            if tkey == 'paths':
+                for k, v in tval.items():
+                    output['paths'][k] = v
+            else:
+                output[tkey] = tval
 
     paths = output['paths']
     definitions = output['definitions']

setup.py

@@ -7,11 +7,16 @@
     long_description = file.read()
 
 setup(name='flask-swagger',
-      version='0.2.10',
+      version='0.2.11',
       url='https://github.com/gangverk/flask-swagger',
       description='Extract swagger specs from your flask project',
       author='Atli Thorbjornsson',
       license='MIT',
-      py_modules=['flask_swagger'],
+      py_modules=['flask_swagger', 'build_swagger_spec'],
       long_description=long_description,
-      install_requires=['Flask>=0.10', 'PyYAML>=3.0'])
+      install_requires=['Flask>=0.10', 'PyYAML>=3.0'],
+      entry_points = """
+      [console_scripts]
+      flaskswagger = build_swagger_spec:run
+      """
+      )