Skip to main content

Helpers, syntaxic sugar and Swagger documentation for Flask-Restful

Project description

==============
Flask RestPlus
==============

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_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.response(404, 'Todo not found')
@api.doc(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.response(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 <http://flask-restplus.readthedocs.org/en/0.8.4/>`_


.. _Swagger: http://swagger.io/
.. _Flask-Restful: http://flask-restful.readthedocs.org/en/latest/

Changelog
=========

0.8.4 (2015-12-07)
------------------

- Drop/merge `flask_restful.Resource` resolving a recursion problem
- Allow any `callable` as field `default`, `min`, `max`...
- Added :class:`~flask_restplus.fields.Date`
- 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 :class:`~flask_restplus.errors.RestError`
- Renamed `MarshallingException` into :class:`~flask_restplus.fields.MarshallingError`
- :class:`~flask_restplus.fields.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



.. _Fields Masks Documentation: http://flask-restplus.readthedocs.org/en/stable/mask.html

Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Files for flask-restplus, version 0.8.4
Filename, size File type Python version Upload date Hashes
Filename, size flask_restplus-0.8.4-py2.py3-none-any.whl (1.1 MB) File type Wheel Python version 2.7 Upload date Hashes View hashes
Filename, size flask-restplus-0.8.4.tar.gz (1.1 MB) File type Source Python version None Upload date Hashes View hashes

Supported by

Elastic Elastic Search Pingdom Pingdom Monitoring Google Google BigQuery Sentry Sentry Error logging AWS AWS Cloud computing DataDog DataDog Monitoring Fastly Fastly CDN SignalFx SignalFx Supporter DigiCert DigiCert EV certificate StatusPage StatusPage Status page