flask-restplus 0.13.0

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

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:

$ 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='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

Contribution

Want to contribute! That’s awesome! Check out CONTRIBUTING.rst! Changelog =========

0.13.0 (2019-08-12)

• Add new Wildcard fields (#255)

• Fix ABC deprecation warnings (#580)

• Fix @api.expect(…, validate=False) decorators for an Api where validate=True is set on the constructor (#609, #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)

• Do not serialize empty tags descriptions

• Ensure consumes is properly set when using form parameters on classes

• Ensure parameters are not duplicated (#164, #196, #234)

• Publish sources distribution (#500, #515)

• Fix late resources registeration (#483)

• Don’t include namespaces without resources to the SWAGGER documentation (#470)

• Add support for checkbox validation input + consistent behavior between inputs and fields. (#461)

• Fix missing enum34 dependency (#444)

0.11.0 (2018-05-16)

• Add authorizations parsing to namespace (#403)

• Add vendor extensions support (#97)

• RequestParser arguments now support the split action

• Ensure default boolean value as False works with RequestParser (#199)

• Schema errors are not longuer hidden by AttributeError: Api does not have __schema__ attribute (#194)

• Add a new URL validator, more flexible and precise.

• Fix error bundling (#175, #144)

• Help message is now added to source error message instead of string interpolation (#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)

• 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):

  • @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)

• Basic support for custom URL converters (#243)

• Support custom response classes inheriting from BaseResponse (#245)

• Allow models to preserve order (#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)

• Add validation for lists in the expect decorator (#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)

• Fix an issue with error handlers (#141)

• Fix an issue with Postman export when using OAuth (#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)

• 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