Helpers, syntaxic sugar and Swagger documentation for Flask-Restful
Project description
Flask-RestPlus provides syntaxic sugar, helpers and automatically generated Swagger documentation on top of Flask-Restful.
Compatibility
Flask-RestPlus requires Python 2.7+.
Installation
You can install Flask-Restplus with pip:
$ pip install flask-restplus
or with easy_install:
$ easy_install flask-restplus
Quick start
With Flask-Restplus, you only import the api instance to route and document your endpoints.
from flask import Flask
from flask.ext.restplus import Api, Resource, fields
app = Flask(__name__)
api = Api(app, version='1.0', title='Todo API',
description='A simple TODO API extracted from the original flask-restful example',
)
ns = api.namespace('todos', description='TODO operations')
TODOS = {
'todo1': {'task': 'build an API'},
'todo2': {'task': '?????'},
'todo3': {'task': 'profit!'},
}
todo = api.model('Todo', {
'task': fields.String(required=True, description='The task details')
})
listed_todo = api.model('ListedTodo', {
'id': fields.String(required=True, description='The todo ID'),
'todo': fields.Nested(todo, description='The Todo')
})
def abort_if_todo_doesnt_exist(todo_id):
if todo_id not in TODOS:
api.abort(404, "Todo {} doesn't exist".format(todo_id))
parser = api.parser()
parser.add_argument('task', type=str, required=True, help='The task details', location='form')
@ns.route('/<string:todo_id>')
@api.doc(responses={404: 'Todo not found'}, params={'todo_id': 'The Todo ID'})
class Todo(Resource):
'''Show a single todo item and lets you delete them'''
@api.doc(description='todo_id should be in {0}'.format(', '.join(TODOS.keys())))
@api.marshal_with(todo)
def get(self, todo_id):
'''Fetch a given resource'''
abort_if_todo_doesnt_exist(todo_id)
return TODOS[todo_id]
@api.doc(responses={204: 'Todo deleted'})
def delete(self, todo_id):
'''Delete a given resource'''
abort_if_todo_doesnt_exist(todo_id)
del TODOS[todo_id]
return '', 204
@api.doc(parser=parser)
@api.marshal_with(todo)
def put(self, todo_id):
'''Update a given resource'''
args = parser.parse_args()
task = {'task': args['task']}
TODOS[todo_id] = task
return task
@ns.route('/')
class TodoList(Resource):
'''Shows a list of all todos, and lets you POST to add new tasks'''
@api.marshal_list_with(listed_todo)
def get(self):
'''List all todos'''
return [{'id': id, 'todo': todo} for id, todo in TODOS.items()]
@api.doc(parser=parser)
@api.marshal_with(todo, code=201)
def post(self):
'''Create a todo'''
args = parser.parse_args()
todo_id = 'todo%d' % (len(TODOS) + 1)
TODOS[todo_id] = {'task': args['task']}
return TODOS[todo_id], 201
if __name__ == '__main__':
app.run(debug=True)
Documentation
The documentation is hosted on Read the Docs
Changelog
0.8.1 (2015-11-27)
- Refactor Swagger UI handling:
allow to register a custom view with @api.documentation
allow to register a custom URL with the doc parameter
allow to disable documentation with doc=False
Added fields mask support through header (see: Fields Masks Documentation)
Expose flask_restful.inputs module on flask_restplus.inputs
- Added support for some missing fields and attributes:
host root field (filed only if SERVER_NAME config is set)
custom tags root field
exclusiveMinimum and exclusiveMaximum number field attributes
multipleOf number field attribute
minLength and maxLength string field attributes
pattern string field attribute
minItems and maxItems list field attributes
uniqueItems list field attribute
Allow to override the default error handler
Fixes
0.8.0
Added payload validation (initial implementation based on jsonschema)
Added @api.deprecated to mark resources or methods as deprecated
Added @api.header decorator shortcut to document headers
Added Postman export
Fix compatibility with flask-restful 0.3.4
Allow to specify an exemple a custom fields with __schema_example__
Added support for PATCH method in Swagger UI
Upgraded to Swagger UI 2.1.2
Handle enum as callable
Allow to configure docExpansion with the SWAGGER_UI_DOC_EXPANSION parameter
0.7.2
Compatibility with flask-restful 0.3.3
Fix action=append handling in RequestParser
Upgraded to SwaggerUI 2.1.8-M1
Miscellaneous fixes
0.7.1
Fix @api.marshal_with_list() keyword arguments handling.
0.7.0
Expose models and fields schema through the __schema__ attribute
Drop support for model as class
Added @api.errorhandler() to register custom error handlers
Added @api.response'' shortcut decorator
Fix list nested models missing in definitions
0.6.0
Python 2.6 support
- Experimental polymorphism support (single inheritance only)
Added Polymorph field
Added discriminator attribute support on String fields
Added api.inherit() method
Added ClassName field
0.5.1
Fix for parameter with schema (do not set type=string)
0.5.0
Allow shorter syntax to set operation id: @api.doc('my-operation')
Added a shortcut to specify the expected input model: @api.expect(my_fields)
Added title attribute to fields
Added @api.extend() to extend models
Ensure coherence between required and allow_null for NestedField
Support list of primitive types and list of models as body
Upgraded to latest version of Swagger UI
Fixes
0.4.2
Rename apidoc blueprint into restplus_doc to avoid collisions
0.4.1
Added SWAGGER_VALIDATOR_URL config parameter
Added readonly field parameter
Upgraded to latest version of Swagger UI
0.4.0
Port to Flask-Restful 0.3+
Use the default Blueprint/App mecanism
Allow to hide some ressources or methods using @api.doc(False) or @api.hide
Allow to globally customize the default operationId with the default_id callable parameter
0.3.0
- Switch to Swagger 2.0 (Major breakage)
notes documentation is now description
nickname documentation is now id
new responses declaration format
Added missing body parameter to document body input
Last release before Flask-Restful 0.3+ compatibility switch
0.2.4
Handle description and required attributes on fields.List
0.2.3
Fix custom fields registeration
0.2.2
Fix model list in declaration
0.2.1
Allow to type custom fields with Api.model
Handle custom fields into fieds.List
0.2
Upgraded to SwaggerUI 0.2.22
Support additional field documentation attributes: required, description, enum, min, max and default
Initial support for model in RequestParser
0.1.3
Fix Api.marshal() shortcut
0.1.2
Added Api.marshal_with() and Api.marshal_list_with() decorators
Added Api.marshal() shortcut
0.1.1
Use zip_safe=False for proper packaging.
0.1
Initial release
Release history Release notifications | RSS feed
Download files
Download the file for your platform. If you're not sure which to choose, learn more about installing packages.
Source Distribution
Built Distribution
File details
Details for the file flask-restplus-0.8.1.tar.gz.
File metadata
- Download URL: flask-restplus-0.8.1.tar.gz
- Upload date:
- Size: 1.0 MB
- Tags: Source
- Uploaded using Trusted Publishing? No
File hashes
| Algorithm | Hash digest | |
|---|---|---|
| SHA256 | 2fafc6a71483f798e222ef58ffaaebe5ad408a2ef123a198e1e79eb53ae88d3c |
|
| MD5 | a2e28705b732271da810df828363a98e |
|
| BLAKE2b-256 | 38ae7447f2c515906849027eab2e2b0acd425aa86aa5ae096e822cbd6f03da49 |
Provenance
File details
Details for the file flask_restplus-0.8.1-py2.py3-none-any.whl.
File metadata
- Download URL: flask_restplus-0.8.1-py2.py3-none-any.whl
- Upload date:
- Size: 1.1 MB
- Tags: Python 2, Python 3
- Uploaded using Trusted Publishing? No
File hashes
| Algorithm | Hash digest | |
|---|---|---|
| SHA256 | 273fbda867e6bfe2cf62a6da05613fec8cfbb7db954dfe0d33af7132d49391a1 |
|
| MD5 | c8d9d38d0da5724f8b62fa62a0550ffe |
|
| BLAKE2b-256 | bba706b92130ad7b1384e68569e564a551db7c2bb326cbcc40df02c8821d9a68 |
