{
"info": {
"author": "Bruno Rocha",
"author_email": "rochacbruno@gmail.com",
"bugtrack_url": null,
"classifiers": [],
"description": "# flasgger\nCreates Swagger 2.0 API documentation for all your Flask views extracting specs from docstrings or referenced YAML files.\n\nThe Swagger UI is embedded and docs by default available in **/apidocs/index.html**\n\n[](https://landscape.io/github/rochacbruno/flasgger/master)\n\n[![wercker status](https://app.wercker.com/status/d86586341ba8b313162b36f84b192a9c/m \"wercker status\")](https://app.wercker.com/project/bykey/d86586341ba8b313162b36f84b192a9c)\n\n
\n\nflasgger provides an extension (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.\n\n# DEMO app\n\nhttp://flasgger-rochacbruno.rhcloud.com/\n\n**Powered by OpenShift**\n\n\n# Getting started\n\n## create a virtualenv\n\n```\nmkvirtualenv test_api\n```\n\n## install dependencies\n```\npip install flask\npip install flasgger\n```\n## create a file called simple_test.py\n\n```python\nfrom flask import Flask, jsonify, request\nfrom flasgger import Swagger\n\napp = Flask(__name__)\n\nSwagger(app)\n\n\n@app.route(\"/recs\", methods=['GET'])\ndef recs():\n \"\"\"\n A simple test API\n This endpoint does nothing\n Only returns \"test\"\n ---\n tags:\n - testapi\n parameters:\n - name: size\n in: query\n type: string\n description: size of elements\n responses:\n 200:\n description: A single user item\n schema:\n id: return_test\n properties:\n result:\n type: string\n description: The test\n default: 'test'\n \"\"\"\n size = int(request.args.get('size', 1))\n return jsonify({\"result\": \"test\" * size})\n\napp.run(debug=True)\n```\n## run\n\n```python\npython simple_test.py\n```\n\n## try\n\n- http://localhost:5000/apidocs/index.html\n\n# Install\n\n```\npip install flasgger\n```\n\n# Run demo app\n\n```\npython -m flasgger.example_app\n```\n\nAccess: http://localhost:5000 to see the demo app running\n\n## you can run in gunicorn\n\n```\npip install gunicorn\n\ngunicorn flasgger.example_app:app -b 0.0.0.0:5000\n\n```\n\n# A simple example\n\n```python\nfrom flask import Flask, jsonify\nfrom flasgger import Swagger\n\napp = Flask(__name__)\nSwagger(app)\n\n@app.route('/api/')\ndef user_api(username):\n \"\"\"\n User API\n This resource returns user information\n ---\n tags:\n - users\n parameters:\n - name: username\n in: path\n type: string\n required: true\n responses:\n 200:\n description: A single user item\n schema:\n id: user_response\n properties:\n username:\n type: string\n description: The username\n default: some_username\n\n \"\"\"\n return jsonify({'username': username})\n\n\napp.run()\n\n```\n\n> NOTE: when catching arguments in path always use explicit types, bad: ``/api/`` good: ``/api/``\n\nThe api docs and playground for the above app will be available in [http://localhost:5000/apidocs/index.html](http://localhost:5000/apidocs/index.html)\n\n# using external files\n\nIf you don't like to put YAML on docstrings you can use an external file\nusing yaml or yml extension and following the same pattern.\n\n### external_file.yml\n```yaml\nFirst line is the summary\nAll following lines until the hyphens is added to description\nthe format of the first lines until 3 hyphens will be not yaml compliant\nbut everything below the 3 hyphens should be.\n---\ntags:\n - users\nparameters:\n - in: path\n name: username\n type: string\n required: true\nresponses:\n 200:\n description: A single user item\n schema:\n id: rec_username\n properties:\n username:\n type: string\n description: The name of the user\n default: 'steve-harris'\n\n```\n\nAnd then use this file as spec to a view\n\n```python\nfrom flasgger.utils import swag_from\n\n@app.route('/api/')\n@swag_from('path/to/external_file.yml')\ndef fromfile_decorated(username):\n return jsonify({'username': username})\n```\n\nOr if you don't want to use the decorator you can simply use the shortcut\n\n```python\n@app.route('/api/')\ndef fromfile_decorated(username):\n \"\"\"\n file: path/to/external_file.yml\n \"\"\"\n return jsonify({'username': username})\n\n```\n\n> NOTE: the above example only works for a single definition\n\n# Handling multiple http methods and routes for a single function\n\nYou can separate specifications by endpoint or methods\n\n```python\nfrom flasgger.utils import swag_from\n\n@app.route('/api/', endpoint='with_user_name', methods=['PUT', 'GET'])\n@app.route('/api/', endpoint='without_user_name')\n@swag_from('path/to/external_file.yml', endpoint='with_user_name')\n@swag_from('path/to/external_file_no_user_get.yml', endpoint='without_user_name', methods=['GET'])\n@swag_from('path/to/external_file_no_user_put.yml', endpoint='without_user_name', methods=['PUT'])\ndef fromfile_decorated(username=None):\n if not username:\n return \"No user!\"\n return jsonify({'username': username})\n```\n\n# Use the same yaml file to validate your API data\n\n```\nfrom flasgger.utils import validate, ValidationError\n\n@swag_from('defs.yml')\ndef post():\n data = request.json\n try:\n validate(data, 'schema_id', 'defs.yml', __file__)\n except ValidationError:\n return abort(500)\n```\n\nAll validation options can be found at http://json-schema.org/latest/json-schema-validation.html\n\n# HTML sanitizer\n\nBy default Flasgger will try to sanitize the content in YAML definitions\nreplacing every ```\\n``` with ```
``` but you can change this behaviour\nsetting another kind of sanitizer.\n\n```\nfrom flasgger import Swagger, NO_SANITIZER\n\napp =Flask()\nSwagger(app, sanitizer=NO_SANITIZER)\n```\n\nYou can write your own sanitizer\n\n```\nSwagger(app, sanitizer=lambda text: do_anything_with(text))\n```\n\nThere is also a Markdown parser available, if you want to be able to render\nMarkdown in your specs description use **MK_SANITIZER**\n\n\n# More\n\nflasgger supports docstrings in methods of MethodView classes (ala [Flask-RESTful](https://github.com/flask-restful/flask-restful)) and regular Flask view functions.\n\nFollowing YAML conventions, flasgger 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.\n\nIn order to support inline definition of [Schema ](https://github.com/swagger-api/swagger-spec/blob/master/versions/2.0.md#schemaObject) objects in [Parameter](https://github.com/swagger-api/swagger-spec/blob/master/versions/2.0.md#parameterObject) and [Response](https://github.com/swagger-api/swagger-spec/blob/master/versions/2.0.md#responsesObject) objects, flasgger 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.\n\n[Schema ](https://github.com/swagger-api/swagger-spec/blob/master/versions/2.0.md#schemaObject) objects can also be defined within the properties of other [Schema ](https://github.com/swagger-api/swagger-spec/blob/master/versions/2.0.md#schemaObject) objects . An example is shown above with the address property of User.\n\n\n# example app\n\nTo expose your Swagger specification to the world you provide a Flask route that does something along these lines\n\nThis is the DEMO app included in **flasgger/example_app.py**\n\n```python\nfrom flask import Flask, jsonify, request\nfrom flask.views import MethodView\nfrom flasgger import Swagger\n\napp = Flask(__name__)\n\n\n# config your API specs\n# you can define multiple specs in the case your api has multiple versions\n# ommit configs to get the default (all views exposed in /spec url)\n# rule_filter is a callable that receives \"Rule\" object and\n# returns a boolean to filter in only desired views\n\napp.config['SWAGGER'] = {\n \"swagger_version\": \"2.0\",\n # headers are optional, the following are default\n # \"headers\": [\n # ('Access-Control-Allow-Origin', '*'),\n # ('Access-Control-Allow-Headers', \"Authorization, Content-Type\"),\n # ('Access-Control-Expose-Headers', \"Authorization\"),\n # ('Access-Control-Allow-Methods', \"GET, POST, PUT, DELETE, OPTIONS\"),\n # ('Access-Control-Allow-Credentials', \"true\"),\n # ('Access-Control-Max-Age', 60 * 60 * 24 * 20),\n # ],\n # another optional settings\n # \"url_prefix\": \"swaggerdocs\",\n # \"subdomain\": \"docs.mysite,com\",\n # specs are also optional if not set /spec is registered exposing all views\n \"specs\": [\n {\n \"version\": \"0.0.1\",\n \"title\": \"Api v1\",\n \"endpoint\": 'v1_spec',\n \"route\": '/v1/spec',\n\n # rule_filter is optional\n # it is a callable to filter the views to extract\n\n # \"rule_filter\": lambda rule: rule.endpoint.startswith(\n # 'should_be_v1_only'\n # )\n }\n ]\n}\n\nswagger = Swagger(app) # you can pass config here Swagger(app, config={})\n\n\nclass UserAPI(MethodView):\n\n def get(self, team_id):\n \"\"\"\n Get a list of users\n First line is the summary\n All following lines until the hyphens is added to description\n ---\n tags:\n - users\n parameters:\n - name: team_id\n in: path\n description: ID of team (type any number)\n required: true\n type: integer\n responses:\n 200:\n description: Returns a list of users\n schema:\n type: array\n items:\n $ref: '#/definitions/User'\n \"\"\"\n data = {\n \"users\": [\n {\"name\": \"Steven Wilson\", \"team\": team_id},\n {\"name\": \"Mikael Akerfeldt\", \"team\": team_id},\n {\"name\": \"Daniel Gildenlow\", \"team\": team_id}\n ]\n }\n return jsonify(data)\n\n def post(self, team_id):\n \"\"\"\n Create a new user\n First line is the summary\n All following lines until the hyphens is added to description\n ---\n tags:\n - users\n parameters:\n - name: team_id\n in: path\n description: ID of team (type any number)\n required: true\n type: integer\n - in: body\n name: body\n schema:\n id: User\n required:\n - team\n - name\n properties:\n team:\n type: integer\n description: team for user\n name:\n type: string\n description: name for user\n responses:\n 201:\n description: User created\n schema:\n type: array\n items:\n $ref: '#/definitions/User'\n \"\"\"\n return jsonify({\"newuser\": request.json, \"team_id\": team_id})\n\n\nview = UserAPI.as_view('users')\napp.add_url_rule(\n '/v1/users/',\n view_func=view,\n methods=[\"GET\", \"POST\"],\n endpoint='should_be_v1_only_users'\n)\n\n# you can still use @app.route if you want\n\n\nif __name__ == \"__main__\":\n app.run(debug=True)\n\n```\n\nthen access [http://localhost:5000/apidocs/index.html](http://localhost:5000/apidocs/index.html) to see api docs in action\n\nAcknowledgments\n\nFlassger uses Swagger UI [Swagger-UI](https://github.com/swagger-api/swagger-ui)\n\n\nFlasgger is a fork of [Flask-Swagger](https://github.com/gangverk/flask-swagger) which is a simpler solution, consider it if you just want to expose specs json.\n\n\n",
"description_content_type": "",
"docs_url": null,
"download_url": "",
"downloads": {
"last_day": -1,
"last_month": -1,
"last_week": -1
},
"home_page": "https://github.com/theodo/flasgger/",
"keywords": "",
"license": "MIT",
"maintainer": "",
"maintainer_email": "",
"name": "flasgger-TheodoFork",
"package_url": "https://pypi.org/project/flasgger-TheodoFork/",
"platform": "any",
"project_url": "https://pypi.org/project/flasgger-TheodoFork/",
"project_urls": {
"Homepage": "https://github.com/theodo/flasgger/"
},
"release_url": "https://pypi.org/project/flasgger-TheodoFork/0.5.13/",
"requires_dist": [
"Flask (>=0.10)",
"PyYAML (>=3.0)",
"jsonschema (>=2.5.1)",
"mistune"
],
"requires_python": "",
"summary": "Extract swagger specs from your flask project",
"version": "0.5.13"
},
"last_serial": 4568593,
"releases": {
"0.5.13": [
{
"comment_text": "",
"digests": {
"md5": "3a2d965cd9c2b28753dec6f94a84fcc1",
"sha256": "32a150393b10ce227fb9f3c51fca73d5d09114595972ef8b23d23a1dfb6ccaaa"
},
"downloads": -1,
"filename": "flasgger_TheodoFork-0.5.13-py3-none-any.whl",
"has_sig": false,
"md5_digest": "3a2d965cd9c2b28753dec6f94a84fcc1",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": null,
"size": 1133431,
"upload_time": "2018-12-06T16:52:59",
"url": "https://files.pythonhosted.org/packages/b2/6c/f4bbefcb706c278b49680e0295475592aa68ff2b8284804fed2fd6f8dc69/flasgger_TheodoFork-0.5.13-py3-none-any.whl"
}
]
},
"urls": [
{
"comment_text": "",
"digests": {
"md5": "3a2d965cd9c2b28753dec6f94a84fcc1",
"sha256": "32a150393b10ce227fb9f3c51fca73d5d09114595972ef8b23d23a1dfb6ccaaa"
},
"downloads": -1,
"filename": "flasgger_TheodoFork-0.5.13-py3-none-any.whl",
"has_sig": false,
"md5_digest": "3a2d965cd9c2b28753dec6f94a84fcc1",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": null,
"size": 1133431,
"upload_time": "2018-12-06T16:52:59",
"url": "https://files.pythonhosted.org/packages/b2/6c/f4bbefcb706c278b49680e0295475592aa68ff2b8284804fed2fd6f8dc69/flasgger_TheodoFork-0.5.13-py3-none-any.whl"
}
]
}