fixes #1 using id instead of name

getsling · Mar 7, 2015 · 6e48449 · 6e48449
1 parent 51497d4
commit 6e48449
Show file tree

Hide file tree

Showing 5 changed files with 124 additions and 15 deletions.
diff --git a/README b/README
@@ -0,0 +1,112 @@
+flask-swagger
+=============
+
+A swagger 2.0 spec extractor for flask
+
+Install:
+
+::
+
+    pip install flask-swagger
+
+flask-swagger provides a method (swagger) that inspects the flask app
+for endpoints that contain YAML docstrings with swagger 2.0
+`Operation <https://github.com/swagger-api/swagger-spec/blob/master/versions/2.0.md#operation-object>`__
+objects.
+
+::
+
+    class UserAPI(MethodView):
+
+        def post(self):
+            """
+            Create a new user
+            ---
+            tags:
+              - users
+            parameters:
+              - in: body
+                name: body
+                schema:
+                  id: User
+                  required:
+                    - email
+                    - name
+                  properties:
+                    email:
+                      type: string
+                      description: email for user
+                    name:
+                      type: string
+                      description: name for user
+            responses:
+              201:
+                description: User created
+            """
+            return {}
+
+flask-swagger supports docstrings in MethodView classes and regular
+flask view functions.
+
+Following YAML conventions, flask-swagger searches for ``---``,
+everything preceding is provided as ``summary`` (first line) and
+``description`` (following lines) for the endpoint while everything
+after is parsed as a swagger
+`Operation <https://github.com/swagger-api/swagger-spec/blob/master/versions/2.0.md#operation-object>`__
+object.
+
+In order to support inline definition of
+`Schema <https://github.com/swagger-api/swagger-spec/blob/master/versions/2.0.md#schemaObject>`__
+objects in
+`Operation <https://github.com/swagger-api/swagger-spec/blob/master/versions/2.0.md#operation-object>`__
+and
+`Response <https://github.com/swagger-api/swagger-spec/blob/master/versions/2.0.md#responsesObject>`__
+items, flask-swagger veers a little off from the standard. We require an
+``id`` field for the inline Schema which is then used to correctly place
+the
+`Schema <https://github.com/swagger-api/swagger-spec/blob/master/versions/2.0.md#schemaObject>`__
+object in the
+`Definitions <https://github.com/swagger-api/swagger-spec/blob/master/versions/2.0.md#definitionsObject>`__
+object.
+
+To expose your swagger specification to the world you provide a flask
+route that does something along these lines
+
+::
+
+    from flask import Flask, jsonify
+    from flask_swagger import swagger
+
+    app = Flask(__name__)
+
+    @app.route("/spec")
+    def spec():
+        return jsonify(swagger(app))
+
+Note that the swagger specification returned by ``swagger(app)`` is as
+minimal as it can be. It's your job to override and add to the
+specification as you see fit.
+
+::
+
+    @app.route("/spec")
+    def spec():
+        swag = swagger(app)
+        swag['info']['version'] = "1.0"
+        swag['info']['title'] = "My API"
+        return jsonify(swag)
+
+`Swagger-UI <https://github.com/swagger-api/swagger-ui>`__
+
+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.
+
+Acknowledgments
+
+flask-swagger builds on ideas and code from
+`flask-sillywalk <https://github.com/hobbeswalsh/flask-sillywalk>`__ and
+`flask-restful-swagger <https://github.com/rantav/flask-restful-swagger>`__
diff --git a/README.md b/README.md
@@ -5,7 +5,7 @@ Install:
 ```
 pip install flask-swagger
 ```
-flask-swagger provides a method (swagger) that inspects the flask app for endpoints that contain YAML docstrings with swagger 2.0 [Operation](https://github.com/swagger-api/swagger-spec/blob/master/versions/2.0.md#operation-object) objects. 
+flask-swagger provides a method (swagger) that inspects the flask app for endpoints that contain YAML docstrings with swagger 2.0 [Operation](https://github.com/swagger-api/swagger-spec/blob/master/versions/2.0.md#operation-object) objects.
 
 ```
 class UserAPI(MethodView):
@@ -20,7 +20,7 @@ class UserAPI(MethodView):
           - in: body
             name: body
             schema:
-              name: User
+              id: User
               required:
                 - email
                 - name
@@ -41,7 +41,7 @@ flask-swagger supports docstrings in MethodView classes and regular flask view f
 
 Following YAML conventions, flask-swagger searches for `---`, everything preceding is provided as `summary` (first line) and `description` (following lines) for the endpoint while everything after is parsed as a swagger [Operation](https://github.com/swagger-api/swagger-spec/blob/master/versions/2.0.md#operation-object) object.
 
-In order to support inline definition of [Schema ](https://github.com/swagger-api/swagger-spec/blob/master/versions/2.0.md#schemaObject) objects in [Operation](https://github.com/swagger-api/swagger-spec/blob/master/versions/2.0.md#operation-object)  and [Response](https://github.com/swagger-api/swagger-spec/blob/master/versions/2.0.md#responsesObject) items, flask-swagger veers a little off from the standard. We add (and require) a `name` field for the inline Schema which is then used to correctly place the [Schema](https://github.com/swagger-api/swagger-spec/blob/master/versions/2.0.md#schemaObject) object in the [Definitions](https://github.com/swagger-api/swagger-spec/blob/master/versions/2.0.md#definitionsObject) object.
+In order to support inline definition of [Schema ](https://github.com/swagger-api/swagger-spec/blob/master/versions/2.0.md#schemaObject) objects in [Operation](https://github.com/swagger-api/swagger-spec/blob/master/versions/2.0.md#operation-object)  and [Response](https://github.com/swagger-api/swagger-spec/blob/master/versions/2.0.md#responsesObject) items, flask-swagger veers a little off from the standard. We require an `id` field for the inline Schema which is then used to correctly place the [Schema](https://github.com/swagger-api/swagger-spec/blob/master/versions/2.0.md#schemaObject) object in the [Definitions](https://github.com/swagger-api/swagger-spec/blob/master/versions/2.0.md#definitionsObject) object.
 
 To expose your swagger specification to the world you provide a flask route that does something along these lines
 
@@ -75,5 +75,3 @@ Swagger-UI is the reason we embarked on this mission to begin with, flask-swagge
 Acknowledgments
 
 flask-swagger builds on ideas and code from [flask-sillywalk](https://github.com/hobbeswalsh/flask-sillywalk) and [flask-restful-swagger](https://github.com/rantav/flask-restful-swagger)
-
-
diff --git a/examples/example.py b/examples/example.py
@@ -30,7 +30,7 @@ def post(self):
           - in: body
             name: body
             schema:
-              name: User
+              id: User
               required:
                 - email
                 - name
@@ -71,7 +71,7 @@ def bla():
       200:
         description: Hacked some hacks
         schema:
-          name: Hack
+          id: Hack
           properties:
             hack:
               type: string

diff --git a/flask_swagger.py b/flask_swagger.py
@@ -45,11 +45,11 @@ def _extract_definitions(alist):
         for params in alist:
             schema = params.get("schema")
             if schema is not None:
-                schema_name = schema.get("name")
-                if schema_name is not None:
+                schema_id = schema.get("id")
+                if schema_id is not None:
                     defs.append(schema)
                     params['schema'] = {
-                        "$ref": "#/definitions/{}".format(schema_name)
+                        "$ref": "#/definitions/{}".format(schema_id)
                     }
     return defs
 
@@ -100,9 +100,9 @@ def spec():
                 if responses is not None:
                     defs = defs + _extract_definitions(responses.values())
                 for definition in defs:
-                    name = definition.get('name')
-                    if name is not None:
-                        definitions[name] = definition
+                    def_id = definition.get('id')
+                    if def_id is not None:
+                        definitions[def_id] = definition
                 operations[verb] = dict(
                     summary=summary,
                     description=description,

diff --git a/setup.py b/setup.py
@@ -7,12 +7,11 @@
     long_description = file.read()
 
 setup(name='flask-swagger',
-      version='0.1.1',
+      version='0.2.0',
       url='https://github.com/gangverk/flask-swagger',
       description='Extract swagger specs from your flast-restful project',
       author='Atli Thorbjornsson',
       license='MIT',
       py_modules=['flask_swagger'],
       long_description=long_description,
       install_requires=['Flask>=0.10', 'PyYAML>=3.0'])
-