Fully featured framework for fast, easy and documented API development with Flask
.. image:: https://secure.travis-ci.org/noirbizarre/flask-restplus.svg?tag=0.13.0 :target: https://travis-ci.org/noirbizarre/flask-restplus?tag=0.13.0 :alt: Build status .. image:: https://coveralls.io/repos/noirbizarre/flask-restplus/badge.svg?tag=0.13.0 :target: https://coveralls.io/r/noirbizarre/flask-restplus?tag=0.13.0 :alt: Code coverage .. image:: https://readthedocs.org/projects/flask-restplus/badge/?version=0.13.0 :target: https://flask-restplus.readthedocs.io/en/0.13.0/ :alt: Documentation status .. image:: https://img.shields.io/pypi/l/flask-restplus.svg :target: https://pypi.org/project/flask-restplus :alt: License .. image:: https://img.shields.io/pypi/pyversions/flask-restplus.svg :target: https://pypi.org/project/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_.
Flask-RestPlus requires Python 2.7 or 3.4+.
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
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)
Flask-RESTPlus is brought to you by @noirbizarre. Since early 2019 @SteadBytes, @a-luna, @j5awry, @ziirish volunteered to help @noirbizarre keep the project up and running. Of course everyone is welcome to contribute and we will be happy to review your PR's or answer to your issues.
The documentation is hosted on Read the Docs <http://flask-restplus.readthedocs.io/en/latest/>_
.. _Flask: http://flask.pocoo.org/ .. _Swagger: http://swagger.io/
CONTRIBUTING.rst! <https://github.com/noirbizarre/flask-restplus/blob/master/CONTRIBUTING.rst>_
ChangelogWildcard fields (#255 <https://github.com/noirbizarre/flask-restplus/pull/255>_)#580 <https://github.com/noirbizarre/flask-restplus/pull/580>_)@api.expect(..., validate=False) decorators for an Api where validate=True is set on the constructor (#609 <https://github.com/noirbizarre/flask-restplus/issues/609>, #610 <https://github.com/noirbizarre/flask-restplus/pull/610>)basePath is always a pathResource$ref and description (or other property) output is valid (using allOf)#475 <https://github.com/noirbizarre/flask-restplus/issues/475>_)consumes is properly set when using form parameters on classes#164 <https://github.com/noirbizarre/flask-restplus/issues/164>, #196 <https://github.com/noirbizarre/flask-restplus/issues/196>, #234 <https://github.com/noirbizarre/flask-restplus/issues/234>_)#500 <https://github.com/noirbizarre/flask-restplus/issues/500>, #515 <https://github.com/noirbizarre/flask-restplus/issues/515>)#483 <https://github.com/noirbizarre/flask-restplus/issues/483>_)#470 <https://github.com/noirbizarre/flask-restplus/issues/470>_)#461 <https://github.com/noirbizarre/flask-restplus/issues/461>_)enum34 dependency (#444 <https://github.com/noirbizarre/flask-restplus/issues/444>_)#403 <https://github.com/noirbizarre/flask-restplus/issues/403>_)#97 <https://github.com/noirbizarre/flask-restplus/issues/97>_)RequestParser arguments now support the split actionFalse works with RequestParser (#199 <https://github.com/noirbizarre/flask-restplus/issues/199>_)AttributeError: Api does not have __schema__ attribute (#194 <https://github.com/noirbizarre/flask-restplus/issues/194>_)URL validator, more flexible and precise.#175 <https://github.com/noirbizarre/flask-restplus/issues/175>, #144 <https://github.com/noirbizarre/flask-restplus/issues/144>)#147 <https://github.com/noirbizarre/flask-restplus/issues/147>_)skip_none, in marshal_with and marshal#217 <https://github.com/noirbizarre/flask-restplus/issues/217>_)allow_null and NestedApi and Namespace now accept an optionnal ordered parametermarshal_with and marshal now accept an optionnal ordered parameterBreaking changes
- Drop python 2.6 support
- Improve header handling (`#119 <https://github.com/noirbizarre/flask-restplus/issues/119>`_):
- `@api.header` only document response headers on all responses
- `@api.response` accept an optionnal `headers` argument to document response specific headers
- request header are handled by the `@api.expect` decorator
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
FAQs
Fully featured framework for fast, easy and documented API development with Flask
We found that flask-restplus demonstrated a healthy version release cadence and project activity because the last version was released less than a year ago. It has 1 open source maintainer collaborating on the project.
Did you know?
Socket for GitHub automatically highlights issues in each pull request and monitors the health of all your open source dependencies. Discover the contents of your packages and block harmful activity before you install or update your dependencies.
Security News
In this segment of the Risky Business podcast, Feross Aboukhadijeh and Patrick Gray discuss the challenges of tracking malware discovered in open source softare.
Research
Security News
A threat actor's playbook for exploiting the npm ecosystem was exposed on the dark web, detailing how to build a blockchain-powered botnet.
Security News
NVD’s backlog surpasses 20,000 CVEs as analysis slows and NIST announces new system updates to address ongoing delays.