Helpers, syntaxic sugar and Swagger documentation for Flask-Restful
Project description
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:
- 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 fielddefault
,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 intoerrors
- Renamed
RestException
into RestError - Renamed
MarshallingException
into MarshallingError - DateTime field always output datetime
- Renamed
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 details
Release history Release notifications
Download files
Download the file for your platform. If you're not sure which to choose, learn more about installing packages.
Filename, size | File type | Python version | Upload date | Hashes |
---|---|---|---|---|
Filename, size flask_restplus-0.8.6-py2.py3-none-any.whl (1.1 MB) | File type Wheel | Python version 2.7 | Upload date | Hashes View hashes |
Filename, size flask-restplus-0.8.6.tar.gz (1.1 MB) | File type Source | Python version None | Upload date | Hashes View hashes |
Close
Hashes for flask_restplus-0.8.6-py2.py3-none-any.whl
Algorithm | Hash digest | |
---|---|---|
SHA256 | 91d9866d2a33d33ea01eaebf42358e7d7806938bbab7d5d00062073ddfa7608d |
|
MD5 | 170155a154c46f7b5e6896d1437f73c2 |
|
BLAKE2-256 | 60b786c7fe869045abe6672554f28a60ffff812015e828fb63aecc53063cd0fd |