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 (ala Flask-RESTful) 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 also support schema objects nested within the properties of other Schema objects. An example is shown above with the address property of User.
If you don't like to put YAML on docstrings you can put the same content in an external file.
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: