Skip to main content
This is a pre-production deployment of Warehouse. Changes made here affect the production instance of PyPI (pypi.python.org).
Help us improve Python packaging - Donate today!

Fully featured framework for fast, easy and documented API development with Flask

Project Description
==============
Flask RestPlus
==============

.. image:: https://secure.travis-ci.org/noirbizarre/flask-restplus.svg?tag=0.10.1
:target: http://travis-ci.org/noirbizarre/flask-restplus?tag=0.10.1
:alt: Build status
.. image:: https://coveralls.io/repos/noirbizarre/flask-restplus/badge.svg?tag=0.10.1
:target: https://coveralls.io/r/noirbizarre/flask-restplus?tag=0.10.1
:alt: Code coverage
.. image:: https://readthedocs.org/projects/flask-restplus/badge/?version=0.10.1
:target: http://flask-restplus.readthedocs.io/en/latest/
:alt: Documentation status
.. image:: https://img.shields.io/pypi/l/flask-restplus.svg
:target: https://pypi.python.org/pypi/flask-restplus
:alt: License
.. image:: https://img.shields.io/pypi/pyversions/flask-restplus.svg
:target: https://pypi.python.org/pypi/flask-restplus
:alt: Supported Python versions
.. image:: https://badges.gitter.im/Join%20Chat.svg
:alt: Join the chat at https://gitter.im/noirbizarre/flask-restplus
:target: https://gitter.im/noirbizarre/flask-restplus?utm_source=badge&utm_medium=badge&utm_campaign=pr-badge&utm_content=badge

Flask-RESTPlus is an extension for `Flask`_ that adds support for quickly building REST APIs.
Flask-RESTPlus encourages best practices with minimal setup.
If you are familiar with Flask, Flask-RESTPlus should be easy to pick up.
It provides a coherent collection of decorators and tools to describe your API
and expose its documentation properly using `Swagger`_.


Compatibility
=============

Flask-RestPlus requires Python 2.7+.


Installation
============

You can install Flask-Restplus with pip:

.. code-block:: console

$ pip install flask-restplus

or with easy_install:

.. code-block:: console

$ easy_install flask-restplus


Quick start
===========

With Flask-Restplus, you only import the api instance to route and document your endpoints.

.. code-block:: python

from flask import Flask
from flask_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 <http://flask-restplus.readthedocs.io/en/latest/>`_


.. _Flask: http://flask.pocoo.org/
.. _Swagger: http://swagger.io/

Changelog
=========



0.10.1 (2017-03-04)
-------------------

- Fix a typo in ``__init__`` breaking ``from flask_restplus import *`` (`#242 <https://github.com/noirbizarre/flask-restplus/issues/242>`_)
- Basic support for custom URL converters (`#243 <https://github.com/noirbizarre/flask-restplus/issues/243>`_)
- Support custom response classes inheriting from ``BaseResponse`` (`#245 <https://github.com/noirbizarre/flask-restplus/issues/245>`_)
- Allow models to preserve order (`#135 <https://github.com/noirbizarre/flask-restplus/issues/135>`_)

0.10.0 (2017-02-12)
-------------------

- Allows to specify a custom mount path on namespace registration
- Allow to express models as raw schemas
- Upgraded to Swagger-UI 2.2.6
- Support Swagger-UI translations
- Fix prefix trailing slash stripping in Postman doc generation (`#232 <https://github.com/noirbizarre/flask-restplus/issues/232>`_)
- Add validation for lists in the expect decorator (`#231 <https://github.com/noirbizarre/flask-restplus/issues/231>`_)

0.9.2 (2016-04-22)
------------------

- Same version but a PyPI bug force reupload.

0.9.1 (2016-04-22)
------------------

- Added some Swagger-UI Oauth configurations:
- `SWAGGER_UI_OAUTH_CLIENT_ID`
- `SWAGGER_UI_OAUTH_REALM`
- `SWAGGER_UI_OAUTH_APP_NAME`
- Expose ``type: object`` in Swagger schemas (`#157 <https://github.com/noirbizarre/flask-restplus/issues/157>`_)
- Fix an issue with error handlers (`#141 <https://github.com/noirbizarre/flask-restplus/issues/141>`_)
- Fix an issue with Postman export when using OAuth (`#151 <https://github.com/noirbizarre/flask-restplus/issues/151>`_)
- Miscellenaous code and documentation fixes
- Remove last flask-restful references (unless needed) and add missing attributions

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 <https://github.com/noirbizarre/flask-restplus/issues/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 <http://flask-restplus.readthedocs.org/en/stable/mask.html>`_)
- 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 History

This version
History Node

0.10.1

History Node

0.10.0

History Node

0.9.2

History Node

0.9.0

History Node

0.8.6

History Node

0.8.5

History Node

0.8.4

History Node

0.8.3

History Node

0.8.2

History Node

0.8.1

History Node

0.8.0

History Node

0.7.2

History Node

0.7.1

History Node

0.7.0

History Node

0.6.0

History Node

0.5.1

History Node

0.5.0

History Node

0.4.2

History Node

0.4.1

History Node

0.4.0

History Node

0.3.0

History Node

0.2.4

History Node

0.2.3

History Node

0.2.2

History Node

0.2.1

History Node

0.2

History Node

0.1.3

History Node

0.1.2

History Node

0.1.1

History Node

0.1

Download Files

Download Files

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

File Name & Checksum SHA256 Checksum Help Version File Type Upload Date
flask_restplus-0.10.1-py2.py3-none-any.whl (1.0 MB) Copy SHA256 Checksum SHA256 2.7 Wheel Mar 4, 2017
flask-restplus-0.10.1.tar.gz (985.0 kB) Copy SHA256 Checksum SHA256 Source Mar 4, 2017

Supported By

WebFaction WebFaction Technical Writing Elastic Elastic Search Pingdom Pingdom Monitoring Dyn Dyn DNS Sentry Sentry Error Logging CloudAMQP CloudAMQP RabbitMQ Heroku Heroku PaaS Kabu Creative Kabu Creative UX & Design Fastly Fastly CDN DigiCert DigiCert EV Certificate Rackspace Rackspace Cloud Servers DreamHost DreamHost Log Hosting