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='TodoMVC API',
description='A simple TodoMVC API',
)
ns = api.namespace('todos', description='TODO operations')
todo = api.model('Todo', {
'id': fields.Integer(readOnly=True, description='The task unique identifier'),
'task': fields.String(required=True, description='The task details')
})
class TodoDAO(object):
def __init__(self):
self.counter = 0
self.todos = []
def get(self, id):
for todo in self.todos:
if todo['id'] == id:
return todo
api.abort(404, "Todo {} doesn't exist".format(id))
def create(self, data):
todo = data
todo['id'] = self.counter = self.counter + 1
self.todos.append(todo)
return todo
def update(self, id, data):
todo = self.get(id)
todo.update(data)
return todo
def delete(self, id):
todo = self.get(id)
self.todos.remove(todo)
DAO = TodoDAO()
DAO.create({'task': 'Build an API'})
DAO.create({'task': '?????'})
DAO.create({'task': 'profit!'})
@ns.route('/')
class TodoList(Resource):
'''Shows a list of all todos, and lets you POST to add new tasks'''
@ns.doc('list_todos')
@ns.marshal_list_with(todo)
def get(self):
'''List all tasks'''
return DAO.todos
@ns.doc('create_todo')
@ns.expect(todo)
@ns.marshal_with(todo, code=201)
def post(self):
'''Create a new task'''
return DAO.create(api.payload), 201
@ns.route('/<int:id>')
@ns.response(404, 'Todo not found')
@ns.param('id', 'The task identifier')
class Todo(Resource):
'''Show a single todo item and lets you delete them'''
@ns.doc('get_todo')
@ns.marshal_with(todo)
def get(self, id):
'''Fetch a given resource'''
return DAO.get(id)
@ns.doc('delete_todo')
@ns.response(204, 'Todo deleted')
def delete(self, id):
'''Delete a task given its identifier'''
DAO.delete(id)
return '', 204
@ns.expect(todo)
@ns.marshal_with(todo)
def put(self, id):
'''Update a task given its identifier'''
return DAO.update(id, api.payload)
if __name__ == '__main__':
app.run(debug=True)
Documentation
The documentation is hosted on Read the Docs
Changelog
0.9.0 (2016-02-22)
Make Namespace behave like Blueprint for Flask
Deprecated parser and body parameters for expect in doc decorator
Deprecated Model.extend in favor of Model.clone
Added the param decorator
Honour method restrictions in Swagger documentation (#93)
Improved documentation
0.8.6 (2015-12-26)
Handle callable on API infos
Handle documentation on error handlers
Drop/merge flask_restful flask_restful.RequestParser
Handle RequestParser into expect decorator
Handle schema for inputs parsers
- Added some inputs:
email
ip
ipv4
ipv6
0.8.5 (2015-12-12)
Handle mask on Polymorph field
Handle mask on inherited models
Replace flask_restful.abort by flask_restplus.errors.abort
Replace flask_restful.unpack by flask_restplus.utils.unpack
- Breaking changes:
Renamed ApiModel into Model
Renamed ApiNamespace into Namespace
0.8.4 (2015-12-07)
Drop/merge flask_restful.Resource resolving a recursion problem
Allow any callable as field default, min, max…
Added Date field
Improve error handling for inconsistent masks
Handle model level default mask
support colons and dashes in mask field names
- Breaking changes:
Renamed exceptions module into errors
Renamed RestException into RestError
Renamed MarshallingException into MarshallingError
DateTime field always output datetime
0.8.3 (2015-12-05)
Drop/merge flask-restful fields
Drop/merge flask-restplus inputs
Update Swagger-UI to version 2.1.3
Use minified version of Swagger-UI if DEBUG=False
Blueprint subdomain support (static only)
Added support for default fields mask
0.8.2 (2015-12-01)
Skip unknown fields in mask when applied on a model
Added * token to fields mask (all remaining fields)
Ensure generated endpoints does not collide
Drop/merge flask-restful Api.handler_error()
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
Hashes for flask_restplus-0.9.0-py2.py3-none-any.whl
| Algorithm | Hash digest | |
|---|---|---|
| SHA256 | 154768dfc22aaad67cb1f4ce91dcaa58d97791fb6820ed40d05cdaccda701f35 |
|
| MD5 | c565271eb9f213e62e6a574f06e3dac6 |
|
| BLAKE2b-256 | cb5c33a621cc8a740a76a95821a619971a988fe77dcef4e932b417f60ff138e2 |
