Swagger ui¶

You can turn off swaggger ui by ui argument:

from flask import Flask
from flask.ext.restplus import Api

app = Flask(__name__)
api = Api(app, ui=False)

If you need ui on custom url (default is “/”), you can disable default ui and register it manually:

from flask import Flask
from flask.ext.restplus import Api, apidoc

app = Flask(__name__)
api = Api(app, ui=False)

@api.route('/doc/', endpoint='doc')
def swagger_ui():
    return apidoc.ui_for(api)

app.register_blueprint(apidoc.apidoc)  # only needed for assets and templates

Route with decorator¶

The Api class has a route() decorator used to route API’s endpoint.

When with Flask-Restful you were writting :

class MyResource(Resource):
    def get(self, id):
        return {}

api.add_resource('/my-resource/<id>', MyResource.as_view('my-resource'))

With Flask-Restplus, you can write:

@api.route('/my-resource/<id>', endpoint='my-resource')
class MyResource(Resource):
    def get(self, id):
        return {}

You can optionnaly provide class-wide documentation:

@api.route('/my-resource/<id>', endpoint='my-resource', doc={params:{'id': 'An ID'}})
class MyResource(Resource):
    def get(self, id):
        return {}

But it will be easier to read with two decorators for the same effect:

@api.route('/my-resource/<id>', endpoint='my-resource')
@api.doc(params={'id': 'An ID'})
class MyResource(Resource):
    def get(self, id):
        return {}

The namespace object provide the same feature:

ns = api.namespace('ns', 'Some namespace')

# Will ba available to /api/ns/my-resource/<id>
@ns.route('/my-resource/<id>', endpoint='my-resource')
class MyResource(Resource):
    def get(self, id):
        return {}

All routes within a namespace are prefixed with the namespace name.

abort shortcut¶

You can use the Api.abort() method to abort a request. This shortcut always serialize the response in the right format.

@api.route('/failure')
class MyResource(Resource):
    def get(self):
        api.abort(403)

    def post(self):
        api.abort(500, 'Some custom message')

parser shortcut¶

You can use the Api.parser() shortcut to obtain a RequestParser instance.

parser = api.parser()
parser.add_argument('param', type=str, help='Some parameter')

marshal shortcut¶

You can use the Api.marshal() shortcut to serialize your objects.

return api.marshal(todos, fields), 201

Handle errors with @api.errorhandler() decorator¶

The @api.errorhandler() decorator allows you to register a specific handler for a given exception, in the same maner than you can do with Flask/Blueprint @errorhandler decorator.

@api.errorhandler(CustomException)
def handle_custom_exception(error):
    '''Return a custom message and 400 status code'''
    return {'message': 'What you want'}, 400


@api.errorhandler(AnotherException)
def handle_another_exception(error):
    '''Return a custom message and 500 status code'''
    return {'message': error.specific}

Documenting with the @api.doc() decorator¶

This decorator allows you specify some details about your API. They will be used in the Swagger API declarations.

You can document a class or a method.

@api.route('/my-resource/<id>', endpoint='my-resource')
@api.doc(params={'id': 'An ID'})
class MyResource(Resource):
    def get(self, id):
        return {}

    @api.doc(responses={403: 'Not Authorized'})
    def post(self, id):
        api.abort(403)

Documenting with the @api.model() decorator¶

The @api.model decorator allows you to declare the models that your API can serialize.

You can also extend fields and use the __schema_format__ and __schema_type__ to specify the produced types:

my_fields = api.model('MyModel', {
    'name': fields.String,
    'age': fields.Integer(min=0)
})

class MyIntField(fields.Integer):
    __schema_format__ = 'int64'

class MySpecialField(fields.Raw):
    __schema_type__ = 'some-type'
    __schema_format__ = 'some-format'

parent = api.model('Parent', {
    'name': fields.String
})

child = api.extend('Child', parent, {
    'age': fields.Integer
})

parent = api.model('Parent', {
    'name': fields.String,
    'class': fields.String(discriminator=True)
})

child = api.inherit('Child', parent, {
    'extra': fields.String
})

"Child": {
    "properties": {
        "name": {"type": "string"},
        "class": {"type": "string"}
    },
    "discriminator": "class",
    "required": ["class"]
},
"Child": {
    "allOf": [{
            "$ref": "#/definitions/Parent"
        }, {
            "properties": {
                "extra": {"type": "string"}
            }
        }
    ]
}

mapping = {
    Child1: child1_fields,
    Child2: child2_fields,
}

fields = api.model('Thing', {
    owner: fields.Polymorph(mapping)
})

Documenting with the @api.marshal_with() decorator¶

This decorator works like the Flask-Restful marshal_with decorator with the difference that it documents the methods. The optionnal parameter as_list allows you to specify wether or not the objects are returned as a list.

resource_fields = api.model('Resource', {
    'name': fields.String,
})

@api.route('/my-resource/<id>', endpoint='my-resource')
class MyResource(Resource):
    @api.marshal_with(resource_fields, as_list=True)
    def get(self):
        return get_objects()

    @api.marshal_with(resource_fields)
    def post(self):
        return create_object()

The @pi.marshal_list_with() decorator is strictly equivalent to Api.marshal_with(fields, as_list=True).

resource_fields = api.model('Resource', {
    'name': fields.String,
})

@api.route('/my-resource/<id>', endpoint='my-resource')
class MyResource(Resource):
    @api.marshal_list_with(resource_fields)
    def get(self):
        return get_objects()

    @api.marshal_with(resource_fields)
    def post(self):
        return create_object()

Documenting with the @api.expect() decorator¶

The @api.expect() decorator allows you to specify the expected input fields and is a shortcut for @api.doc(body=<fields>).

The following synatxes are equivalents:

resource_fields = api.model('Resource', {
    'name': fields.String,
})

@api.route('/my-resource/<id>')
class MyResource(Resource):
    @api.expect(resource_fields)
    def get(self):
        pass

resource_fields = api.model('Resource', {
    'name': fields.String,
})

@api.route('/my-resource/<id>')
class MyResource(Resource):
    @api.doc(body=resource_fields)
    def get(self):
        pass

It allows you specify lists as expected input too:

resource_fields = api.model('Resource', {
    'name': fields.String,
})

@api.route('/my-resource/<id>')
class MyResource(Resource):
    @api.expect([resource_fields])
    def get(self):
        pass

Documenting with the @api.response() decorator¶

The @api.response() decorator allows you to document the known responses and is a shortcut for @api.doc(responses='...').

The following synatxes are equivalents:

@api.route('/my-resource/')
class MyResource(Resource):
    @api.response(200, 'Success')
    @api.response(400, 'Validation Error')
    def get(self):
        pass


@api.route('/my-resource/')
class MyResource(Resource):
    @api.doc(responses={
        200: 'Success',
        400: 'Validation Error'
    })
    def get(self):
        pass

You can optionnaly specify a response model as third argument:

model = api.model('Model', {
    'name': fields.String,
})

@api.route('/my-resource/')
class MyResource(Resource):
    @api.response(200, 'Success', model)
    def get(self):
        pass

If you use the @api.marshal_with() decorator, it automatically document the response:

model = api.model('Model', {
    'name': fields.String,
})

@api.route('/my-resource/')
class MyResource(Resource):
    @api.response(400, 'Validation error')
    @api.marshal_with(model, code=201, description='Object created')
    def post(self):
        pass

At least, you can specify a default response sent without knowing the response code

@api.route('/my-resource/')
class MyResource(Resource):
    @api.response('default', 'Error')
    def get(self):
        pass

Documenting with the @api.route() decorator¶

You can provide class-wide documentation by using the Api.route()‘s’ doc parameter. It accept the same attribute/syntax than the Api.doc() decorator.

By example, these two declaration are equivalents:

@api.route('/my-resource/<id>', endpoint='my-resource')
@api.doc(params={'id': 'An ID'})
class MyResource(Resource):
    def get(self, id):
        return {}

@api.route('/my-resource/<id>', endpoint='my-resource', doc={params:{'id': 'An ID'}})
class MyResource(Resource):
    def get(self, id):
        return {}

Documenting the fields¶

Every Flask-Restplus fields accepts additional but optional arguments used to document the field:

• required: a boolean indicating if the field is always set (default: False)
• description: some details about the field (default: None)

There is also field specific attributes.

The String field accept an optional enum argument to restrict the authorized values.

The Integer, Float and Arbitrary fields accept both min and max arguments to restrict the possible values.

my_fields = api.model('MyModel', {
    'name': fields.String(description='The name', required=True),
    'type': fields.String(description='The object type', enum=['A', 'B']),
    'age': fields.Integer(min=0),
})

Documenting the methods¶

Each resource will be documented as a Swagger path.

Each resource method (get, post, put, delete, path, options, head) will be documented as a swagger operation.

You can specify the Swagger unique operationId with the id documentation.

@api.route('/my-resource/')
class MyResource(Resource):
    @api.doc(id='get_something')
    def get(self):
        return {}

You can also use the first argument for the same purpose:

@api.route('/my-resource/')
class MyResource(Resource):
    @api.doc('get_something')
    def get(self):
        return {}

If not specified, a default operationId is providen with the following pattern:

{{verb}}_{{resource class name | camelCase2dashes }}

In the previous example, the default generated operationId will be get_my_resource

You can override the default operationId genertor by giving a callable as default_id parameter to your API. This callable will receive two positionnal arguments:

• the resource class name
• this lower cased HTTP method

def default_id(resource, method):
    return ''.join((method, resource))

api = Api(app, default_id=default_id)

In the previous example, the generated operationId will be getMyResource

Each operation will automatically receive the namespace tag. If the resource is attached to the root API, it will receive the default namespace tag.

fields = api.model('MyModel', {
    'name': fields.String(description='The name', required=True),
    'type': fields.String(description='The object type', enum=['A', 'B']),
    'age': fields.Integer(min=0),
})


@api.model(fields={'name': fields.String, 'age': fields.Integer})
class Person(fields.Raw):
    def format(self, value):
        return {'name': value.name, 'age': value.age}


@api.route('/my-resource/<id>', endpoint='my-resource')
@api.doc(params={'id': 'An ID'})
class MyResource(Resource):
    @api.doc(model=fields)
    def get(self, id):
        return {}

    @api.doc(model='MyModel', body=Person)
    def post(self, id):
        return {}

parser = api.parser()
parser.add_argument('param', type=int, help='Some param', location='form')
parser.add_argument('in_files', type=FileStorage, location='files')

@api.route('/with-parser/', endpoint='with-parser')
class WithParserResource(restplus.Resource):
    @api.doc(parser=parser)
    def get(self):
        return {}

Cascading¶

Documentation handling is done in cascade. Method documentation override class-wide documentation. Inherited documentation override parent one.

By example, these two declaration are equivalents:

@api.route('/my-resource/<id>', endpoint='my-resource')
@api.doc(params={'id': 'An ID'})
class MyResource(Resource):
    def get(self, id):
        return {}

@api.route('/my-resource/<id>', endpoint='my-resource')
@api.doc(params={'id': 'Class-wide description'})
class MyResource(Resource):
    @api.doc(params={'id': 'An ID'})
    def get(self, id):
        return {}

You can also provide method specific documentation from a class decoration. The following example will produce the same documentation than the two previous examples:

@api.route('/my-resource/<id>', endpoint='my-resource')
@api.doc(params={'id': 'Class-wide description'})
@api.doc(get={'params': {'id': 'An ID'}})
class MyResource(Resource):
    def get(self, id):
        return {}

Hiding from documentation¶

You can hide some ressources or methods from documentation using one of the following syntaxes:

# Hide the full ressource
@api.route('/resource1/', doc=False)
class Resource1(Resource):
    def get(self):
        return {}

@api.route('/resource2/')
@api.doc(False)
class Resource2(Resource):
    def get(self):
        return {}

@api.route('/resource3/')
@api.hide
class Resource3(Resource):
    def get(self):
        return {}

# Hide methods
@api.route('/resource4/')
@api.doc(delete=False)
class Resource4(Resource):
    def get(self):
        return {}

    @api.doc(False)
    def post(self):
        return {}

    @api.hide
    def put(self):
        return {}

    def delete(self):
        return {}

flask.ext.restplus¶

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 0x7f92edb99f50>, 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

Parameters:

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

as_list(field)¶

Allow to specify nested lists for documentation

doc(shortcut=None, **kwargs)¶

Add some api documentation to the decorated object

errorhandler(exception)¶

Register an error handler for a given exception

expect(body)¶

Specify the expected input model

extend(name, parent, fields)¶

Extend a model (Duplicate all fields)

inherit(name, parent, fields)¶

Inherit a modal (use the Swagger composition pattern aka. allOf)

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, description=None, **kwargs)¶

A decorator specifying the fields to use for serialization.

Parameters:	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.

parser()¶

Instanciate a RequestParser

render_root()¶

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.

Parameters:	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.

flask.ext.restplus.fields¶

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

flask.ext.restplus.reqparse¶

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