https://github.com/getsling/flask-swagger
A swagger 2.0 spec extractor for flask
https://github.com/getsling/flask-swagger
Last synced: 3 months ago
JSON representation
A swagger 2.0 spec extractor for flask
- Host: GitHub
- URL: https://github.com/getsling/flask-swagger
- Owner: getsling
- License: mit
- Created: 2015-03-01T01:08:16.000Z (over 10 years ago)
- Default Branch: master
- Last Pushed: 2021-11-18T17:50:40.000Z (almost 4 years ago)
- Last Synced: 2024-10-29T17:44:14.600Z (11 months ago)
- Language: Python
- Homepage:
- Size: 86.9 KB
- Stars: 457
- Watchers: 29
- Forks: 91
- Open Issues: 21
-
Metadata Files:
- Readme: README
- License: LICENSE
Awesome Lists containing this project
- jimsghstars - getsling/flask-swagger - A swagger 2.0 spec extractor for flask (Python)
README
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
definitions:
- schema:
id: Group
properties:
name:
type: string
description: the group's name
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
address:
description: address for user
schema:
id: Address
properties:
street:
type: string
state:
type: string
country:
type: string
postalcode:
type: string
groups:
type: array
description: list of groups
items:
$ref: "#/definitions/Group"
responses:
201:
description: User created
"""
return {}
Flask-swagger supports docstrings in methods of 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
`Parameter `__
and
`Response `__
objects, 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.
`Schema `__
objects can be defined in a definitions section within the docstrings (see group object above) or within responses or parameters (see user object above). We alo support schema objects nested within the properties of other
`Schema `__
objects. An example is shown above with the address property of User.
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 `__