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

Changelog

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

Project links

Key dates

PyPI data
Data sourced directly from PyPI's database.
  • Released:
Newer release available (0.13.0)

1 maintainer

PyPI data
Data sourced directly from PyPI's database.
Avatar for noirbizarre from gravatar.com noirbizarre

Credits

Author: Axel Haustant

License

MIT License (MIT)

Classifiers

Report project as malware

Download files

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

Source Distribution

flask-restplus-0.8.6.tar.gz (1.1 MB view details)

Uploaded Source

Built Distribution

If you're not sure about the file name format, learn more about wheel file names.

flask_restplus-0.8.6-py2.py3-none-any.whl (1.1 MB view details)

Uploaded Python 2Python 3

File details

Details for the file flask-restplus-0.8.6.tar.gz.

File metadata

File hashes

Hashes for flask-restplus-0.8.6.tar.gz
Algorithm Hash digest
SHA256 3bb76cc156b9a09da62396d82b29fa31e4f27cccf79528538fe7155cf2785593
MD5 fcffd6ab75dc90f7bf66c2528a426abc
BLAKE2b-256 91c9d301a487470dafc33d29878c59b85c4442981b79813ce1045b7f5f74e625

See more details on using hashes here.

File details

Details for the file flask_restplus-0.8.6-py2.py3-none-any.whl.

File metadata

File hashes

Hashes for flask_restplus-0.8.6-py2.py3-none-any.whl
Algorithm Hash digest
SHA256 91d9866d2a33d33ea01eaebf42358e7d7806938bbab7d5d00062073ddfa7608d
MD5 170155a154c46f7b5e6896d1437f73c2
BLAKE2b-256 60b786c7fe869045abe6672554f28a60ffff812015e828fb63aecc53063cd0fd

See more details on using hashes here.

Release history Release notifications | RSS feed

0.13.0

2 files

0.12.1

2 files

0.12.0

2 files

0.11.0

1 file

0.10.1

2 files

0.10.0

2 files

0.9.2

2 files

0.9.0

2 files

This release

0.8.6 This release

2 files

0.8.5

2 files

0.8.4

2 files

0.8.3

2 files

0.8.2

2 files

0.8.1

2 files

0.8.0

2 files

0.7.2

2 files

0.7.1

2 files

0.7.0

2 files

0.6.0

2 files

0.5.1

2 files

0.5.0

1 file

0.4.2

2 files

0.4.1

2 files

0.4.0

2 files

0.3.0

2 files

0.2.4

1 file

0.2.3

1 file

0.2.2

1 file

0.2.1

1 file

0.2

1 file

0.1.3

1 file

0.1.2

1 file

0.1.1

1 file

0.1

1 file

Supported by

AWS Cloud computing and Security Sponsor Datadog Monitoring Depot Continuous Integration Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page