diff --git a/README b/README index e69de29..55c4a2c 100644 --- 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 `__ +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 `__ +object. + +In order to support inline definition of +`Schema `__ +objects in +`Operation `__ +and +`Response `__ +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 `__ +object in the +`Definitions `__ +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 `__ + +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 `__ +to your new flask-swagger endpoint and enjoy. + +Acknowledgments + +flask-swagger builds on ideas and code from +`flask-sillywalk `__ and +`flask-restful-swagger `__ diff --git a/README.md b/README.md index a757f01..5e74e90 100644 --- 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 index e4409a5..ae2cc3b 100644 --- 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 index ee06a11..7abda88 100644 --- 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 index ee951d8..66a2e24 100644 --- a/setup.py +++ b/setup.py @@ -7,7 +7,7 @@ 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', @@ -15,4 +15,3 @@ py_modules=['flask_swagger'], long_description=long_description, install_requires=['Flask>=0.10', 'PyYAML>=3.0']) -