Socket
Socket
Sign inDemoInstall

flask-restplus

Package Overview
Dependencies
0
Maintainers
1
Alerts
File Explorer

Install Socket

Protect your apps from supply chain attacks

Install

flask-restplus

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

    0.13.0

Maintainers
1

Readme

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

.. 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`_.


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

Flask-RestPlus requires Python 2.7 or 3.4+.


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)


Contributors
============

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.


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/


Contribution
============
Want to contribute! That's awesome! Check out `CONTRIBUTING.rst! <https://github.com/noirbizarre/flask-restplus/blob/master/CONTRIBUTING.rst>`_
Changelog
=========



0.13.0 (2019-08-12)
-------------------

- Add new `Wildcard` fields (`#255 <https://github.com/noirbizarre/flask-restplus/pull/255>`_)
- Fix ABC deprecation warnings (`#580 <https://github.com/noirbizarre/flask-restplus/pull/580>`_)
- Fix `@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>`_)
- Ensure `basePath` is always a path
- Hide Namespaces with all hidden Resources from Swagger documentation
- Per route Swagger documentation for multiple routes on a ``Resource``

0.12.1 (2018-09-28)
-------------------

- Fix missing changelog inprevious release
- Ensure definitions with both `$ref` and description (or other property) output is valid (using `allOf`)
- Added initial specifications schemas and validation support
- Ensure empty enums are not serialized (to have a valid specification)

0.12.0 (2018-09-27)
-------------------

- Fix Namespace decorators (`#475 <https://github.com/noirbizarre/flask-restplus/issues/475>`_)
- Do not serialize empty tags descriptions
- Ensure `consumes` is properly set when using form parameters on classes
- Ensure parameters are not duplicated (`#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>`_)
- Publish sources distribution (`#500 <https://github.com/noirbizarre/flask-restplus/issues/500>`_, `#515 <https://github.com/noirbizarre/flask-restplus/issues/515>`_)
- Fix late resources registeration (`#483 <https://github.com/noirbizarre/flask-restplus/issues/483>`_)
- Don't include namespaces without resources to the SWAGGER documentation (`#470 <https://github.com/noirbizarre/flask-restplus/issues/470>`_)
- Add support for checkbox validation input + consistent behavior between inputs and fields. (`#461 <https://github.com/noirbizarre/flask-restplus/issues/461>`_)
- Fix missing `enum34` dependency (`#444 <https://github.com/noirbizarre/flask-restplus/issues/444>`_)

0.11.0 (2018-05-16)
-------------------

- Add authorizations parsing to namespace (`#403 <https://github.com/noirbizarre/flask-restplus/issues/403>`_)
- Add vendor extensions support (`#97 <https://github.com/noirbizarre/flask-restplus/issues/97>`_)
- ``RequestParser`` arguments now support the ``split`` action
- Ensure default boolean value as `False` works with ``RequestParser`` (`#199 <https://github.com/noirbizarre/flask-restplus/issues/199>`_)
- Schema errors are not longuer hidden by `AttributeError: Api does not have __schema__ attribute` (`#194 <https://github.com/noirbizarre/flask-restplus/issues/194>`_)
- Add a new ``URL`` validator, more flexible and precise.
- Fix error bundling (`#175 <https://github.com/noirbizarre/flask-restplus/issues/175>`_, `#144 <https://github.com/noirbizarre/flask-restplus/issues/144>`_)
- Help message is now added to source error message instead of string interpolation (`#147 <https://github.com/noirbizarre/flask-restplus/issues/147>`_)
- Use pytest instead of nosetests
- Upgrade to Swagger-UI 3.4.0
- Fix typo in comments
- Add an optional key argument, ``skip_none``, in ``marshal_with`` and ``marshal``
- Fix masks not working correctly with Python 2.7 (`#217 <https://github.com/noirbizarre/flask-restplus/issues/217>`_)
- Fixed typos in doc/scaling
- Add docs for `allow_null` and ``Nested``
- Add Namespace.payload
- **Breaking**: everything is unordered by default because ordering has a serious impact on performances:
    - ``Api`` and ``Namespace`` now accept an optionnal ``ordered`` parameter
    - ``marshal_with`` and ``marshal`` now accept an optionnal ``ordered`` parameter

Breaking 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

Keywords

FAQs


Did you know?

Socket installs a GitHub app to automatically flag issues on every pull request and report the health of your dependencies. Find out what is inside your node modules and prevent malicious activity before you update the dependencies.

Install

Related posts

SocketSocket SOC 2 Logo

Product

  • Package Alerts
  • Integrations
  • Docs
  • Pricing
  • FAQ
  • Roadmap

Stay in touch

Get open source security insights delivered straight into your inbox.


  • Terms
  • Privacy
  • Security

Made with ⚡️ by Socket Inc