class flask_restplus.Api(app=None, version=u'1.0', title=None, description=None, terms_url=None, license=None, license_url=None, contact=None, contact_url=None, contact_email=None, authorizations=None, security=None, ui=True, default_id=<function default_id at 0x7f2880dafcf8>, default=u'default', default_label=u'Default namespace', **kwargs)

The main entry point for the application. You need to initialize it with a Flask Application:

>>> app = Flask(__name__)
>>> api = Api(app)

Alternatively, you can use init_app() to set the Flask application after it has been constructed.

The endpoint parameter prefix all views and resources:

  • The API root/documentation will be {endpoint}.root
  • A resource registered as ‘resource’ will be available as {endpoint}.resource
  • app (flask.Flask) – the Flask application object
  • version (str) – The API version (used in Swagger documentation)
  • title (str) – The API title (used in Swagger documentation)
  • description (str) – The API description (used in Swagger documentation)
  • terms_url (str) – The API terms page URL (used in Swagger documentation)
  • contact (str) – A contact email for the API (used in Swagger documentation)
  • license (str) – The license associated to the API (used in Swagger documentation)
  • license_url (str) – The license page URL (used in Swagger documentation)
  • endpoint (str) – The API base endpoint (default to ‘api).
  • default (str) – The default namespace base name (default to ‘default’)
  • default_label (str) – The default namespace label (used in Swagger documentation)
  • default_mediatype (str) – The default media type to return
  • decorators (list) – Decorators to attach to every resource
  • catch_all_404s (bool) – Use handle_error() to handle 404 errors throughout your app
  • url_part_order – A string that controls the order that the pieces of the url are concatenated when the full url is constructed. ‘b’ is the blueprint (or blueprint registration) prefix, ‘a’ is the api prefix, and ‘e’ is the path component the endpoint is added with
  • errors (dict) – A dictionary to define a custom response for each exception or error raised during a request
  • authorizations (dict) – A Swagger Authorizations declaration as dictionary
abort(code=500, message=None, **kwargs)

Properly abort the current request

add_resource(resource, *urls, **kwargs)

Register a Swagger API declaration for a given API Namespace


Allow to specify nested lists for documentation

doc(show=True, **kwargs)

Add some api documentation to the decorated object

marshal(data, fields)

A shortcut to the marshal helper

marshal_list_with(fields, code=200)

A shortcut decorator for marshal_with(as_list=True, code=code)

marshal_with(fields, as_list=False, code=200, **kwargs)

A decorator specifying the fields to use for serialization.

  • as_list (bool) – Indicate that the return type is a list (for the documentation)
  • code (integer) – Optionnaly give the expected HTTP response code if its different from 200
model(name=None, model=None, **kwargs)

Register a model

Model can be either a dictionnary or a fields.Raw subclass.


Instanciate a RequestParser


Override this method to customize the documentation page

flask_restplus.marshal(data, fields, envelope=None)

Takes raw data (in the form of a dict, list, object) and a dict of fields to output and filters the data based on those fields.

  • data – the actual object(s) from which the fields are taken from
  • fields – a dict of whose keys will make up the final serialized response output
  • envelope – optional key that will be used to envelop the serialized response
>>> from flask.ext.restful import fields, marshal
>>> data = { 'a': 100, 'b': 'foo' }
>>> mfields = { 'a': fields.Raw }
>>> marshal(data, mfields)
OrderedDict([('a', 100)])
>>> marshal(data, mfields, envelope='data')
OrderedDict([('data', OrderedDict([('a', 100)]))])
class flask_restplus.marshal_with(fields, envelope=None)

A decorator that apply marshalling to the return values of your methods.

>>> from flask.ext.restful import fields, marshal_with
>>> mfields = { 'a': fields.Raw }
>>> @marshal_with(mfields)
... def get():
...     return { 'a': 100, 'b': 'foo' }
>>> get()
OrderedDict([('a', 100)])
>>> @marshal_with(mfields, envelope='data')
... def get():
...     return { 'a': 100, 'b': 'foo' }
>>> get()
OrderedDict([('data', OrderedDict([('a', 100)]))])

see flask.ext.restful.marshal()

flask_restplus.abort(http_status_code, **kwargs)

Raise a HTTPException for the given http_status_code. Attach any keyword arguments to the exception for later processing.

exception flask_restplus.RestException(msg)

Base class for all Flask-Restplus Exceptions

exception flask_restplus.SpecsError(msg)

An helper class for incoherent specifications.

exception flask_restplus.ValidationError(msg)

An helper class for validation errors.


All fields accept a required boolean and a description string in kwargs.