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__, __schema_type__ and __schema_example__ to specify the produced types and examples:

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'

class MyVerySpecialField(fields.Raw):
    __schema_example__ = 'hello, world'

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
})

"Parent": {
    "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 optional parameter code allows you to specify the expected HTTP status code (200 by default). The optional parameter as_list allows you to specify whether 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, code=201)
    def post(self):
        return create_object(), 201

The @api.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>). It accepts an optional boolean parameter validate defining wether or not the payload should be validated. The validation behavior can be customized globally by either setting the RESTPLUS_VALIDATE configuration to True or passing validate=True to the API constructor.

The following syntaxes 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

An exemple of on-demand validation:

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

@api.route('/my-resource/<id>')
class MyResource(Resource):
    # Payload validation disabled
    @api.expect(resource_fields)
    def post(self):
        pass

    # Payload validation enabled
    @api.expect(resource_fields, validate=True)
    def post(self):
        pass

An exemple of application-wide validation by config:

app.config['RESTPLUS_VALIDATE'] = True

api = Api(app)

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

@api.route('/my-resource/<id>')
class MyResource(Resource):
    # Payload validation enabled
    @api.expect(resource_fields)
    def post(self):
        pass

    # Payload validation disabled
    @api.expect(resource_fields, validate=False)
    def post(self):
        pass

An exemple of application-wide validation by constructor:

api = Api(app, validate=True)

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

@api.route('/my-resource/<id>')
class MyResource(Resource):
    # Payload validation enabled
    @api.expect(resource_fields)
    def post(self):
        pass

    # Payload validation disabled
    @api.expect(resource_fields, validate=False)
    def post(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 optionally 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)
• example: an example to use when displaying (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 provided 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 generator by giving a callable as default_id parameter to your API. This callable will receive two positional 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 {}

@api.route('/my-resource/')
class MyResource(Resource):
    def get(self):
        data = api.payload

@api.route('/with-headers/')
@api.header('X-Header', 'Some expected header', required=True)
class WithHeaderResource(restplus.Resource):
    @api.header('X-Collection', type=[str], collectionType='csv')
    def get(self):
        pass

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 {}

Marking as deprecated¶

You can mark as deprecated some resources or methods with the @api.deprecated decorator:

# Deprecate the full resource
@api.deprecated
@api.route('/resource1/')
class Resource1(Resource):
    def get(self):
        return {}

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

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

    def put(self):
        return {}

Hiding from documentation¶

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

# Hide the full resource
@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 {}

Documenting autorizations¶

In order to document an authorization you can provide an authorization dictionary to the API constructor:

authorizations = {
    'apikey': {
        'type': 'apiKey',
        'in': 'header',
        'name': 'X-API-KEY'
    }
}
api = Api(app, authorizations=authorizations)

Next, you need to set the authorization documentation on each resource/method requiring it. You can use a decorator to make it easier:

def apikey(func):
    return api.doc(security='apikey')(func)

@api.route('/resource/')
class Resource1(Resource):
    @apikey
    def get(self):
        pass

    @api.doc(security='apikey')
    def post(self):
        pass

You can apply this requirement globally with the security constructor parameter:

authorizations = {
    'apikey': {
        'type': 'apiKey',
        'in': 'header',
        'name': 'X-API-KEY'
    }
}
api = Api(app, authorizations=authorizations, security='apikey')

You can have multiple security schemes:

authorizations = {
    'apikey': {
        'type': 'apiKey',
        'in': 'header',
        'name': 'X-API'
    },
    'oauth2': {
        'type': 'oauth2',
        'flow': 'accessCode',
        'tokenUrl': 'https://somewhere.com/token',
        'scopes': {
            'read': 'Grant read-only access',
            'write': 'Grant read-write access',
        }
    }
}
api = Api(self.app, security=['apikey', {'oauth2': 'read'}], authorizations=authorizations)

And compose/override them at method level:

@api.route('/authorizations/')
class Authorized(Resource):
    @api.doc(security=[{'oauth2': ['read', 'write']}])
    def get(self):
        return {}

You can disable security on a given resource/method by passing None or an empty list as security parameter:

@api.route('/without-authorization/')
class WithoutAuthorization(Resource):
    @api.doc(security=[])
    def get(self):
        return {}

    @api.doc(security=None)
    def post(self):
        return {}

Export as Swagger specifications¶

You can export the Swagger specififcations corresponding to your API.

from flask import json

from myapp import api

print(json.dumps(api.__schema__))

Export as Postman collection¶

To help you testing, you can export your API as a Postman collection.

from flask import json

from myapp import api

urlvars = False  # Build query strings in URLs
swagger = True  # Export Swagger specifications
data = api.as_postman(urlvars=urlvars, swagger=swagger)
print(json.dumps(data))

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>, default=u'default', default_label=u'Default namespace', validate=None, **kwargs)[source]¶

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 validate (bool) – Whether or not the API should perform input payload validation. 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)[source]¶

Properly abort the current request

add_resource(resource, *urls, **kwargs)[source]¶

Register a Swagger API declaration for a given API Namespace

as_list(field)[source]¶

Allow to specify nested lists for documentation

deprecated(func)[source]¶

Mark a resource or a method as deprecated

doc(shortcut=None, **kwargs)[source]¶

Add some api documentation to the decorated object

errorhandler(exception)[source]¶

Register an error handler for a given exception

expect(body, validate=None)[source]¶

Specify the expected input model

extend(name, parent, fields)[source]¶

Extend a model (Duplicate all fields)

header(name, description=None, **kwargs)[source]¶

Specify one of the expected headers

inherit(name, parent, fields)[source]¶

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

marshal(data, fields)[source]¶

A shortcut to the marshal helper

marshal_list_with(fields, **kwargs)[source]¶

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

marshal_with(fields, as_list=False, code=200, description=None, **kwargs)[source]¶

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)[source]¶

Register a model

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

parser()[source]¶

Instanciate a RequestParser

render_root()[source]¶

Override this method to customize the documentation page

response(code, description, model=None, **kwargs)[source]¶

Specify one of the expected responses

flask_restplus.marshal(data, fields, envelope=None)[source]¶

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_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)[source]¶

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

>>> from flask_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_restful.marshal()

flask_restplus.abort(http_status_code, **kwargs)[source]¶

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

exception flask_restplus.RestException(msg)[source]¶

Base class for all Flask-Restplus Exceptions

exception flask_restplus.SpecsError(msg)[source]¶

An helper class for incoherent specifications.

exception flask_restplus.ValidationError(msg)[source]¶

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